Quick start (CLI)
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:
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.
NoteThe quick start templates use
@auth0/auth0-reactfor 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-auth0with 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 --versioncommand. -
npm 10 or later. Check your installed version by using the
npm --versioncommand.
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:
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
clientpackage: -
Client-side app with built-in authorization, using the SDK
clientandxmcpackages:
-
To create a full-stack app:
-
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
clientpackage: -
Full-stack app with custom authorization, using the SDK
clientandxmcpackages:
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.
-
-
In
package.json, updatescripts.devto include the following flags: -
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.
-
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:
-
Start your app by entering the following command in your terminal:
-
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.
-
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.
NoteDuring 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.
-
Start your app by entering the following command in your terminal:
-
If prompted, accept the security warnings.
-
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.
-
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.
NoteDuring 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.tsxis your app's entry point.app/apicontains calls to SitecoreAI APIs.components/providerscontains the SDK initialization and authorization code.components/uicontains Blok-style components, such as cards, buttons, and badges.
- Continue developing your app:
- Make more queries to retrieve data from Sitecore.
- Make mutations to change data in Sitecore.
- Learn more about the Marketplace SDK with the reference documentation.
- Explore other tasks to complete after you finish building your app.