Marketplace Scaffold

Scaffold a New Sitecore Marketplace App

You are helping the user scaffold a new Sitecore Marketplace app using the official Sitecore Marketplace SDK (v0.4).

Step 1: Gather Requirements

Ask the user the following questions (skip any they've already answered):

1. App name — What should the app be called? (default: from $ARGUMENTS if provided) 2. Architecture — Client-side only or full-stack?

• Client-side: UI runs entirely in the iframe, communicates via SDK client. Simpler, no server needed.
• Full-stack: Includes Next.js API routes/server actions for server-side SDK access. Required for Auth0, server-side mutations, or proxying external APIs.

3. Authentication — Built-in (default) or Auth0?

• Built-in: Zero-config, SDK handles auth automatically. Sufficient for most apps.
• Auth0: Required for server-side API access, external service integration, or custom auth flows. Requires Auth0 tenant setup.

4. Optional packages — Which additional SDK packages?

• XM Cloud (`xmc`): Access Sites, Pages, Authoring, Content Transfer, Search, and Agent APIs
• AI Skills (`ai`): Access Brand Review API for AI-powered content analysis

Step 2: Run the Scaffold Command

Based on answers, construct and run the appropriate command:

# Client-side only (built-in auth)
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-client.json

# Client-side + XMC
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-client.json https://marketplace-sdk.sitecorecloud.io/r/xmc.json

# Client-side + AI
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-client.json https://marketplace-sdk.sitecorecloud.io/r/ai.json

# Client-side + XMC + AI
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-client.json https://marketplace-sdk.sitecorecloud.io/r/xmc.json https://marketplace-sdk.sitecorecloud.io/r/ai.json

# Full-stack (Auth0) — adds server-side SDK support
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-auth0.json

# Full-stack + XMC
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-auth0.json https://marketplace-sdk.sitecorecloud.io/r/xmc.json

# Full-stack + AI
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-auth0.json https://marketplace-sdk.sitecorecloud.io/r/ai.json

# Full-stack + XMC + AI
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-auth0.json https://marketplace-sdk.sitecorecloud.io/r/xmc.json https://marketplace-sdk.sitecorecloud.io/r/ai.json

Important: If the user doesn't have a Next.js project yet, scaffold one first:

npx create-next-app@latest <app-name> --typescript --tailwind --eslint --app --src-dir
cd <app-name>

Step 3: Post-Scaffold Setup

After scaffolding completes:

1. Create `.env.local` — See env-template.md for the template. Fill in based on architecture choice.

2. Configure CSP headers — Add iframe embedding headers to next.config.ts:

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          {
            key: "Content-Security-Policy",
            value: "frame-ancestors 'self' https://*.sitecorecloud.io",
          },
        ],
      },
    ];
  },
};

3. Install Blok theme (if not already present):

npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/blok-theme.json

4. Verify setup — Run the dev server and confirm no errors:

npm run dev

Step 4: Explain Next Steps

After successful scaffold, suggest:

• Use /marketplace-add-extension to add extension point routes (custom fields, dashboard widgets, etc.)
• Use /marketplace-sdk-reference to look up SDK APIs
• Use /marketplace-build-component to build UI with the Blok design system
• Use /marketplace-deploy when ready to deploy

Reference Files

• Architecture Guide — Decision matrix for client-side vs full-stack
• Environment Template — .env.local templates per architecture

Architecture Decision Guide

Client-Side vs Full-Stack

Package Selection

What the Scaffold Creates

Client-side (app-client.json)

• lib/sitecore/client.ts — Client initialization with ClientSDK.init()
• lib/sitecore/providers.tsx — React context providers (<SitecoreProvider>)
• hooks/use-sitecore.ts — React hooks for SDK access
• app/layout.tsx updates — Wraps app in providers

Full-stack (app-auth0.json)

• Everything from client-side, plus:
• lib/sitecore/server.ts — Server-side client factories
• app/api/auth/[...auth0]/route.ts — Auth0 route handlers
• middleware.ts — Auth0 middleware

XMC (xmc.json)

• lib/sitecore/xmc.ts — XMC module registration
• Types for all XM Cloud APIs

AI (ai.json)

• lib/sitecore/ai.ts — AI module registration
• Types for Brand Review API

Environment Variable Templates

Client-Side Only (.env.local)

# Sitecore Marketplace SDK
NEXT_PUBLIC_SITECORE_APP_ID=your-app-id-from-portal

Full-Stack with Auth0 (.env.local)

# Sitecore Marketplace SDK
NEXT_PUBLIC_SITECORE_APP_ID=your-app-id-from-portal

# Auth0 Configuration
AUTH0_SECRET=use-openssl-rand-hex-32-to-generate
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_CLIENT_ID=your-auth0-client-id
AUTH0_CLIENT_SECRET=your-auth0-client-secret

# Auth0 Sitecore Connection
AUTH0_AUDIENCE=https://api.sitecorecloud.io
AUTH0_SCOPE=openid profile email

How to Get Values