1. Quick starts

Quick start (CLI)

Version: 0.4

This guide describes how to start developing for the Sitecore Marketplace locally by scaffolding a Next.js App Router app with the Marketplace SDK using a single command. This guide is for building client-side and full-stack apps, with either the built-in authorization or custom authorization.

In this guide, you:

  1. Scaffold an app.

  2. 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.

  • If you decide to use custom authorization, make sure your app has client credentials, and set up a custom DNS for local development.

    Note

    The quick start templates use @auth0/auth0-react for client-side authentication, which provides better support for organizations with multiple environments. When creating client credentials, make sure to select Single-page app (SPA) as the application type, even if you're building a full-stack Next.js app.

    However, the Marketplace SDK does not impose constraints on which Auth0 library you use. If you prefer to use @auth0/nextjs-auth0 with server-side authentication patterns, you can replace the package and adapt the implementation accordingly.

    For more information, refer to the Auth0 documentation.

  • 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.

Scaffold an app

To start development, you scaffold a Next.js App Router app using a single command. This process creates a Next.js App Router project and installs the necessary Marketplace SDK packages, Blok, and additional packages depending on your app requirements.

To scaffold an app:

Client-side

To create a client-side app:

  • Open an empty folder in your code editor, then run one of the following commands depending on your app requirements:

    When prompted, select:

    • Yes for Next.js or Next.js as a monorepo, depending on your preferences.

    • Neutral for base color. Blok will automatically override the default styling.

    • Client-side app with built-in authorization, using the SDK client package:

      npx shadcn@latest add https://blok.sitecore.com/r/marketplace/next/quickstart.json

    • Client-side app with built-in authorization, using the SDK client and xmc packages:

      npx shadcn@latest add https://blok.sitecore.com/r/marketplace/next/quickstart-with-client-side-xmc.json

Full-stack

To create a full-stack app:

  1. Open an empty folder in your code editor, then run one of the following commands depending on your app requirements:

    • Full-stack app with custom authorization, using the SDK client package:

      npx shadcn@latest add https://blok.sitecore.com/r/marketplace/next/quickstart-with-custom-auth.json

    • Full-stack app with custom authorization, using the SDK client and xmc packages:

      npx shadcn@latest add https://blok.sitecore.com/r/marketplace/next/quickstart-with-full-stack-xmc.json

    When prompted, select:

    • Yes for Next.js or Next.js as a monorepo, depending on your preferences.

    • Neutral for base color. Blok will automatically override the default styling.

  2. In package.json, update scripts.dev to include the following flags:

    --experimental-https --hostname myapp.local

  3. In .env.local, update the following variables:

    • NEXT_PUBLIC_SITECORE_APP_ID - with your Marketplace app ID.

    • NEXT_PUBLIC_AUTH0_CLIENT_ID - with your app client ID.

    • NEXT_PUBLIC_APP_BASE_URL - with your custom DNS, for example, https://myapp.local:3000. The base URL must match your app's deployment URL.

  4. Save all your changes.

Open your app in Sitecore

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

To open your app in Sitecore:

Client-side

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

    npm run dev

  2. 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, it displays the application context, and the user interface lets you make calls to SitecoreAI APIs.

  3. On the same page, open your console to find logs related to the Marketplace SDK. Make a call to SitecoreAI APIs in the user interface, and track the related logs in the console.

    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.

Full-stack

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

    npm run dev

  2. If prompted, accept the security warnings.

  3. 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, it displays the application context, and the user interface lets you make calls to SitecoreAI APIs.

  4. On the same page, open your console to find logs related to the Marketplace SDK. Make a call to SitecoreAI APIs in the user interface, and track the related logs in the console.

    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, read the application context, and made a call to SitecoreAI APIs. Next, you can:

  • Explore the project structure:

    • app/page.tsx is your app's entry point.

    • app/api contains calls to SitecoreAI APIs.

    • components/providers contains the SDK initialization and authorization code.

    • components/ui contains Blok-style components, such as cards, buttons, and badges.

  • Continue developing your app:

  • Learn more about the Marketplace SDK with the reference documentation.

  • Explore other tasks to complete after you finish building your app.

A Marketplace application that uses a client-side architecture. Client-side apps run entirely in the user's web browser. All API requests from the app to SitecoreAI APIs run indirectly, via the web browser. Ideal for simple UI extensions and functionalities that don't require server-side processing.

A Marketplace application that uses a full-stack architecture. Full-stack apps include both client-side and server-side components. API requests from the app to SitecoreAI APIs can run directly, server to server. Ideal for AI-powered apps such as AI agents, agentic workflows, and other server-to-server API interactions.

An authorization flow for Marketplace applications that is managed entirely by the Marketplace SDK, abstracting it away from the developer.

Auth0 authorization flow for Marketplace applications that replaces the built-in authorization managed by the Marketplace SDK. Required if your app needs to make server-side API calls to SitecoreAI APIs.

If you have suggestions for improving this article, let us know!