Build Custom Apps for Sitecore XM Cloud Marketplace

The Sitecore App Marketplace for XM Cloud Has Officially Launched

The Sitecore App Marketplace for XM Cloud is now live, opening up extensive possibilities for customizing and extending the platform. This blog consolidates the key development and configuration steps to help you build your first custom app.

I began by setting up a basic standalone application in XM Cloud to understand how the process works. With this capability, you can now create custom tools for your organization—or even apps for the broader Sitecore community. In this blog, we’ll walk through the essential steps to build an app in your development environment and then register and install it in XM Cloud.

What is the Sitecore Marketplace?

The Sitecore Marketplace enables customers, partners, and developers to build and use applications that extend Sitecore’s functionality. This means you can integrate your custom modules into Sitecore XM Cloud through various extension points.

These apps can be:

• Private (available only to your organization), or

• Public (shared with anyone using XM Cloud, though the public marketplace is not available yet).

Step 1: Create Your App in Cloud Portal

1. Log in to the Cloud Portal using an Admin or Owner account.

2. Navigate to Developer Studio > Create App.

   

3. Enter the details:

   • Descriptive name (max 50 characters).

   • Select Custom as the app type.

4. Click Create – your app is now registered and ready for configuration.

Step 2: Configure Your App

• Extension Points: Choose where your app should appear. You can select multiple points and customize the Route URL or Display Name.

• API Access: Select the APIs your app will use. For XM Cloud integration, enable XM Cloud APIs.

  

• Development URL:

  • React apps → http://localhost:5173

  • Next.js apps → http://localhost:3000

• App Logo: Add a public logo URL (or use a temporary one: https://cdn-1.webcatalog.io/catalog/sitecore/sitecore-icon.png?v=1731337318728).

• Activate App: Click Activate > Activate.

Step 3: Set Up Your Development Project

Create a Next.js or React app:

Next.js

npx create-next-app@latest my-test-app
cd my-test-app


React

npm create vite@latest my-test-app
cd my-test-app


Install required SDK packages:

npm install @sitecore-marketplace-sdk/client

npm install @sitecore-marketplace-sdk/xmc # if your app uses XM Cloud APIs

 

Step 4: Create the useMarketplaceClient Hook

Create a custom hook to manage the SDK initialization. In your src folder,

create /utils/hooks/useMarketplaceClient.ts, and paste the below code:

// utils/hooks/useMarketplaceClient.ts
import { ClientSDK } from "@sitecore-marketplace-sdk/client";
import { useEffect, useState, useCallback, useMemo, useRef } from "react";
export interface MarketplaceClientState {
client: ClientSDK | null;
error: Error | null;
isLoading: boolean;
isInitialized: boolean;
}

export interface UseMarketplaceClientOptions {
retryAttempts?: number; // Default: 3
retryDelay?: number; // Default: 1000ms
autoInit?: boolean; // Default: true
}

const DEFAULT_OPTIONS: Required<UseMarketplaceClientOptions> = {
retryAttempts: 3,
retryDelay: 1000,
autoInit: true,
};

let client: ClientSDK | undefined = undefined;

async function getMarketplaceClient() {
if (client) {
return client;
}
const config = {
target: window.parent,
};
client = await ClientSDK.init(config);
return client;
}

export function useMarketplaceClient(options: UseMarketplaceClientOptions = {}) {
const opts = useMemo(() => ({ ...DEFAULT_OPTIONS, ...options }), [options]);

const [state, setState] = useState<MarketplaceClientState>({
client: null,
error: null,
isLoading: false,
isInitialized: false,
});

const isInitializingRef = useRef(false);

const initializeClient = useCallback(async (attempt = 1): Promise<void> => {
let shouldProceed = false;
setState(prev => {
if (prev.isLoading || prev.isInitialized || isInitializingRef.current) {
return prev;
}
shouldProceed = true;
isInitializingRef.current = true;
return { ...prev, isLoading: true, error: null };
});

if (!shouldProceed) return;

try {
const client = await getMarketplaceClient();
setState({
client,
error: null,
isLoading: false,
isInitialized: true,
});
} catch (error) {
if (attempt < opts.retryAttempts) {
await new Promise(resolve => setTimeout(resolve, opts.retryDelay));
return initializeClient(attempt + 1);
}
setState({
client: null,
error: error instanceof Error ? error : new Error('Failed to initialize MarketplaceClient'),
isLoading: false,
isInitialized: false,
});
} finally {
isInitializingRef.current = false;
}
}, [opts.retryAttempts, opts.retryDelay]);

useEffect(() => {
if (opts.autoInit) {
initializeClient();
}
return () => {
isInitializingRef.current = false;
setState({
client: null,
error: null,
isLoading: false,
isInitialized: false,
});
};
}, [opts.autoInit, initializeClient]);

return useMemo(() => ({
...state,
initialize: initializeClient,
}), [state, initializeClient]);

}

This hook handles:

• SDK initialization

• Error handling and retry logic

• Preventing race conditions

import { useState, useEffect } from "react";
import type { ApplicationContext } from "@sitecore-marketplace-sdk/client";
import { useMarketplaceClient } from "../utils/hooks/useMarketplaceClient";
 
export default function Home() {
  const { client, error, isInitialized, isLoading } = useMarketplaceClient();
  const [appContext, setAppContext] = useState<ApplicationContext>();
 
  useEffect(() => {
    if (!error && isInitialized && client) {
      client.query("application.context")
        .then((res) => {
          setAppContext(res.data);
        })
        .catch((error) => {
          console.error("Error retrieving application.context:", error);
        });
    }
  }, [client, error, isInitialized]);
 
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
 
  return (
    <div className="p-4">
      <h1>Welcome to {appContext?.name || 'My Marketplace App'}</h1>
    </div>
  );
}

Step 6: Start Development

Run your app:

Then:

1. Open your Sitecore Cloud Portal.

2. Navigate to Marketplace.

   

    

3. Find your registered app and open it in one of the configured extension points.

4. Your app will now run inside Sitecore with secure communication.