Quick start (manual)

Version: 0.4

This guide describes how to start developing for the Sitecore Marketplace locally by connecting a JavaScript or TypeScript app to Sitecore using the Marketplace SDK. This guide is for building a client-side app with built-in authorization.

In this guide, you:

  1. Create a React (Vite) or Next.js app - if you don't already have one.

  2. Install and initialize the Marketplace SDK, then create your first query.

  3. Open your app in Sitecore.

Prerequisites

Check that you have the following, before getting started:

  • A Marketplace app installed in your Sitecore Cloud Portal organization.

  • Node.js 16 or later. Check your installed version by using the node --version command.

  • npm 10 or later. Check your installed version by using the npm --version command.

    Note

    We strongly recommend that you also install Blok in your app. Blok is the Sitecore product design system, and installing it is the easiest way you can give your app the Sitecore look and feel.

    Matching the Sitecore look and feel is required for public Marketplace apps and strongly recommended for custom Marketplace apps. This is to ensure a consistent user experience for the Sitecore product user.

Create an app

If you don't already have an app, create a JavaScript or TypeScript one.

Install the packages

To install the Marketplace SDK packages in your app, run the following commands:

RequestResponse
npm install @sitecore-marketplace-sdk/client # Required for all Marketplace apps
npm install @sitecore-marketplace-sdk/xmc # Required only if your app uses SitecoreAI APIs
npm install @sitecore-marketplace-sdk/ai # Required only if your app uses AI skills APIs

Initialize the SDK

To initialize the Marketplace SDK:

  1. In your code editor, in the src folder of your app, create a hook, for example, /utils/hooks/useMarketplaceClient.ts.

  2. Paste the following code into your new hook:

  3. In your app's main page, such as App.tsx or pages/index.tsx, initialize the Marketplace client in an Effect Hook and create your first query:

    This script:

    • Uses an Effect Hook to check if the Marketplace client is initialized.

    • Makes a query to retrieve details about your Marketplace app: client.query("application.context")

    • Extracts the app details from the API response and stores it in state: setAppContext(res.data);

    • Displays the app name in the user interface: <h1>Welcome to {appContext?.name}</h1>

  4. Start your app by entering the following command in your terminal:

    RequestResponse
    npm run dev
    Note

    Start your app on the same localhost address that you specified during app configuration.

Open your app in Sitecore

After initializing the SDK, you open your Marketplace app in a Sitecore extension point you selected for it during app configuration.

To open your app in Sitecore:

  1. In your web browser, in the Cloud Portal, find and open your Marketplace app in one of its extension points.

    Your app now appears in Sitecore and the two are securely communicating.

  2. On the same page, open your console to find the logs included in the SDK initialization code.

    Note

    During development, trace console logs in your web browser's console in the Sitecore extension point, not on your app's localhost address.

    Similarly, always preview your app in the Sitecore extension point. Any functionality that requires communication with Sitecore, such as getting application details and calling SitecoreAI APIs, only works in the extension points.

Next steps

You've now displayed your app in Sitecore, set up communication between the two, and made your first query. Next, you can:

Do you have some feedback for us?

If you have suggestions for improving this article,