The scaffold decision tree plus the per-target scaffolds for Content SDK head apps and both Marketplace app shapes. Cross-domain by design.

version
0.6.0
GitHub stars
12

Install

/plugin install sitecore-setup@sitecore-skills-pocs

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Chris1415/sitecore-skills-pocs.

Contents

Discovered from source

Skills 4

Content SDK Head Application Scaffold

Use when: Building a standard SitecoreAI headless rendering host (Next.js app that fetches content from SitecoreAI via Content SDK).

For a Sitecore-managed existing-site rebuild/rebrand, the content-sdk-website-build-flow skill (baseline-first: copy baseline → token-replace → pull) GOVERNS — this skill covers the standalone head-app scaffold step it calls in.

If you haven't decided yet whether this is the right scaffold, run setup-scaffold first.

Canonical command

STEP 0 — pick the template by ROUTER, before running anything

The two template ids produce different routers and are NOT interchangeable. Choosing wrong is not a cosmetic mistake — it silently produces an app in which App-Router requirements (a client component map, a [site] catch-all route, the AppRouterMultisiteProxy chain) simply do not exist, and any App-Router component you then port is unusable.

Router neededTemplate idPost-scaffold proof
App Routernextjs-app-routersrc/app/ exists, src/pages/ does not
App Router + on-demand revalidation (OSR)nextjs-app-router-cache-componentsas above, plus src/app/api/revalidate/route.ts exists and next.config.* sets cacheComponents: true
Pages Routernextjssrc/pages/ exists, src/app/ does not

Choose App Router unless the user explicitly asks for Pages Router. It is the default for new work: every head app the authors of these skills have shipped is App Router, the 16 content-sdk-app-router-* skills target it, and the nextjs-app-router scaffold names its package content-sdk-nextjs-app-router.

App Router — the normal case (agents / CI, non-interactive):

npx --yes create-content-sdk-app@latest --yes --template nextjs-app-router --destination <app-folder-path>

Interactive equivalent (follow prompts for the destination):

npx create-content-sdk-app@latest --template nextjs-app-router

Pages Router — only when explicitly requested. The bare nextjs token is the template id as a first positional, and it yields Pages Router:

npx create-content-sdk-app@latest nextjs
# non-interactive: npx --yes create-content-sdk-app@latest --yes --template nextjs --destination <app-folder-path>

VERIFY THE ROUTER, do not assume it. Immediately after the scaffold, check the expected folder from the table above exists and the other does not. HARD STOP and report if the CLI produced anything else — do not hand-edit next.config.*, move files, or otherwise convert routers by hand. A router mismatch discovered later costs far more than a re-scaffold now.

History: a run took the bare nextjs token from this skill's own headline, got a Pages Router app, and only caught it because App-Router requirements were unsatisfiable. That is why the router choice is now STEP 0 rather than a footnote.

STEP 0b — App Router: plain or cache-components (publish freshness)

Pick by how a publish must reach the live site. The template is the irreversible half: moving a plain app to OSR later is a porting task (content-sdk-app-router-cache-components-and-osr § 8), not a flag.

  • Redeploy after publish, or a revalidate window, is acceptable → nextjs-app-router (the default).
  • Fresh within minutes of a publish, no redeploy → nextjs-app-router-cache-components, then the Edge webhook (sitecoreai-edge-admin-webhooks).
  • Version floor. Up to 2.4.x item-level OSR cannot match a cached page, so every publish purges the whole site. The fix (upstream #619/#620/#623) is only in the 2.5.0 canary as of 2026-10-02. Choosing OSR means choosing explicitly: @latest with the sitewide purge, or @<exact canary version> from npm view create-content-sdk-app dist-tags.canary. Never pin a canary silently, and never use the floating @canary tag.
npx --yes create-content-sdk-app@<latest|exact-canary-version> --yes --template nextjs-app-router-cache-components --destination <app-folder-path>

An existing app keeps its template. Never re-scaffold it to change freshness.

Do not substitute this step with cloning SitecoreAI starter solo-website, degit, or an empty npm init project unless the user explicitly requested that starter.

Failure policy

If the CLI errors (network, permissions, non-empty directory without --force), stop and report the error. Do not recover by hand-assembling a Content SDK app — that breaks the scaffold contract.

Forbidden shortcuts

ShortcutWhy
solo-website / SitecoreAI starter clone or degitNot the official Content SDK generator; couples you to starter layout.
Copying another local app as a "template"Drifts from current CLI defaults and hides updates.
npm init + pasted @sitecore-content-sdk/* depsEasy to miss middleware, proxy, component maps, and config.

Exception: Use SitecoreAI starter or another named starter only when the user explicitly asks for that repo or template.

What the scaffold creates

  • Next.js application pre-configured with @sitecore-content-sdk/* packages (see generated package.json for exact names)
  • Component map setup
  • Layout data fetching (Experience Edge GraphQL)
  • Editing support for SitecoreAI Pages
  • Middleware stack (multisite, personalization, redirects)
  • Environment variable template (.env.example)
  • Sitecore CLI configuration (sitecore.json)

Post-scaffold steps

  1. Wire local env — MANDATORY UPFRONT QUESTION before writing .env.local.
    Ask the user for all five values in a single question before touching .env.local. Do NOT invent, guess, or fill placeholders:

    "To configure .env.local I need these 5 values — please paste them all at once:

    • SITECORE_EDGE_CONTEXT_ID — Cloud Portal → Environment → Edge Context ID*
    • NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID — same value as above (client-side)*
    • NEXT_PUBLIC_DEFAULT_SITE_NAME — the site name (must match the Sites API name)*
    • NEXT_PUBLIC_DEFAULT_LANGUAGE — usually en*
    • SITECORE_EDITING_SECRET — Cloud Portal → SitecoreAI Deploy → Environment → Editing Host → Edit → Editing Secret"*

    Wait for the answer before writing the file. A wrong or invented SITECORE_EDITING_SECRET silently breaks preview/editing with confusing 401 errors at the end of the build — this value must come from the user.

  2. Run dotnet sitecore login to authenticate with SitecoreAI (when using CLI against CM).

  3. Run dotnet sitecore ser push to push serialized items to CM (when applicable).

  4. Run npm run dev or npm run start:connected in the app directory to start the rendering host.

When NOT to use this scaffold

  • An existing project already has a rendering host (extend it instead — don't re-scaffold)
  • The project requires the older JSS API (@sitecore-jss/*) — use the SitecoreAI starter JS template instead
  • The project is a Marketplace integration rather than a rendering host — use setup-marketplace-client-side or setup-marketplace-full-stack instead

Greenfield checklist

  • Picked the template by router (STEP 0) — --template nextjs-app-router for App Router (the default for new work), bare nextjs only if Pages Router was explicitly requested.
  • Picked plain vs cache-components (STEP 0b) by publish freshness; under OSR, recorded which version line (stable sitewide purge vs exact canary pin).
  • Ran the CLI literally, non-interactive form: npx --yes create-content-sdk-app@<version> --yes --template <nextjs-app-router|nextjs-app-router-cache-components|nextjs> --destination ….
  • Verified the router post-scaffold — App Router: src/app/ exists and src/pages/ does not (Pages Router: the reverse). Cache-components: src/app/api/revalidate/route.ts exists and cacheComponents: true is set. HARD STOPPED on any other outcome instead of hand-converting.
  • Did not use solo-website / starter clone as a silent substitute for the CLI.
  • .env.local exists with the required Edge context values so npm run dev can resolve Edge context and API key.
  • Post-scaffold: Edge / editing / sitecore.config.ts follow the generated app — avoid inventing a parallel stack.

What runs after this skill

For a Content SDK head app, after the scaffold is complete you typically pick from:

  • The 17 content-sdk-app-router-* skills (component scaffolding, registration, GraphQL fetching, multisite, sitemap, dictionary/i18n, editing-safe rendering, etc.) when the scaffold produced an App Router project
  • The 11 content-sdk-pages-router-* skills in the sitecore-content-sdk-nextjs-pages-router plugin (per-concern mirrors; not every App Router skill has a twin) when the scaffold produced a Pages Router project

Pick per concern as the implementation plan calls for them.

Marketplace Client-Side Integration Scaffold

Use when: Building a Marketplace integration or SitecoreAI-connected application that is predominantly client-side — postMessage-bridge SDK calls (Mode A), no SSR, no Auth0 PKCE. Typically a browser-only widget, UI extension, or embedded app.

Also use when: the app needs one or two server-side route handlers that proxy a direct Sitecore REST API call (Agent / Pages / Publishing / Sites) using OAuth client_credentials, because the SDK has no wrapper for that endpoint. In that case, follow the main scaffold steps below, then apply the "Optional: server-side OAuth proxy" section near the end of this skill. Do not use the full-stack scaffold for this — its Auth0 PKCE surface is dead weight when there is no logged-in-user-delegated SDK call. (Seen on a screenshot app that picked full-stack, 2026-05-02: it carries this dead weight for good; the client-side + proxy shape is the correct one.)

If you haven't decided yet whether this is the right scaffold, run setup-scaffold first.

SDK-first rule

Before adding the OAuth proxy section: confirm the call you need is not in xmc.*, ai.*, or application.*. If it is, use the SDK over the postMessage bridge (Mode A) — no server route, no client_secret, no proxy. The OAuth proxy is only for endpoints the SDK does not expose. See marketplace-sdk-client, marketplace-sdk-xmc, marketplace-sdk-ai for what the SDK already covers.

Canonical command

Interactive:

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

Non-interactive (agents / CI):

yes '' | npx --yes shadcn@latest add https://blok.sitecore.com/r/marketplace/next/quickstart-with-client-side-xmc.json --yes --cwd <absolute-target-path>

Interactive prompts

Answered automatically by the non-interactive form above — defaults are the recommended values:

PromptDefaultRecommended
Start a new project? (framework)Next.jsNext.js
What is your project named?next-appAccept default unless renaming
Select a component libraryRadixRadix
Which preset would you like to use?Nova (Lucide / Geist)Nova

Output layout — the scaffold creates a next-app/ subdirectory, not in-place

<target>/
└── next-app/
    ├── package.json                           # @sitecore-marketplace-sdk/client + xmc pre-installed
    ├── app/layout.tsx                         # wired to MarketplaceProvider
    ├── app/page.tsx                           # renders the example components
    ├── components/
    │   ├── providers/marketplace.tsx          # ClientSDK.init via React Context (see the marketplace-sdk-client skill, § 2)
    │   ├── examples/built-in-auth/
    │   │   ├── application-context.tsx        # application.context query example
    │   │   └── with-xmc/list-languages.tsx    # xmc.sites.listLanguages example
    │   └── ui/                                # shadcn components
    ├── hooks/
    └── lib/

Flatten the next-app/ subdirectory (recommended default)

The quickstart always lands in a nested next-app/ subdir. When you scaffold into a project where the app root is meant to be a site/ folder, the nested layout duplicates a level of path and forces every downstream implementation plan, test runner, Vercel project root, and doc reference to carry a site/next-app/ prefix. Flatten immediately after the scaffold completes so the Next.js app root IS <your-app-root>/:

# from your project root
mv site/next-app/* site/next-app/.* site/ 2>/dev/null
rmdir site/next-app

Verify the flatten worked: site/package.json must exist at the top level and site/next-app must no longer exist. From this point on the canonical app root is <your-app-root>/site/ — all downstream paths, tests, Vercel project settings, and documentation reference site/, NOT site/next-app/.

If the flatten is NOT applied (e.g. when scaffolding multiple sibling apps under the same parent), every implementation-plan path must include the next-app/ prefix and every downstream reference must match.

What it creates

  • Next.js 16+ app with @sitecore-marketplace-sdk/client + @sitecore-marketplace-sdk/xmc pre-installed
  • components/providers/marketplace.tsx — MarketplaceProvider + useMarketplaceClient + useAppContext hooks (React Context pattern — the scaffold's canonical SDK init shape, see the marketplace-sdk-client skill, § 2)
  • components/examples/built-in-auth/ — working example components for application.context query + XMC listLanguages query (covers the typical first SDK call for a Mode A app)
  • shadcn/ui component setup with Radix + Nova preset (configurable via prompts)

Characteristics

  • No server-side rendering or API routes
  • Communicates with SitecoreAI APIs via the portal postMessage bridge (Mode A, portal-brokered auth — see the marketplace-sdk-lifecycle skill, § 5a)
  • Suited for: dashboards, editors, lightweight portals, UI extensions

Post-scaffold steps

  1. cd <target>/next-app — all subsequent commands run inside the next-app/ subdirectory.

  2. Verify npm install completed (shadcn runs it automatically; confirm package-lock.json exists).

  3. Review the scaffolded components under components/ (NOT src/components/ — Next.js 16 quickstart has no src/ dir).

  4. Fix scaffold lint nits — the quickstart ships components/providers/marketplace.tsx with two small errors that make npm run lint fail out of the box: (a) typo extention → extension; (b) unescaped apostrophe your app's → your app&apos;s (or switch to double-quoted string). Apply both before running lint. Upstream Blok fix is pending; re-check on SDK/quickstart bumps.

    Nova preset Badge API drift — the Nova preset's components/ui/badge.tsx does not use the standard shadcn variant union. Its variant is 'default' | 'bold' (typography); status/intent is expressed through a separate colorScheme prop taking 'neutral' | 'primary' | 'success' | 'danger' | 'warning' | …. Code copied from generic shadcn examples (e.g. <Badge variant="destructive">, <Badge variant="secondary">) will fail tsc --noEmit with Type '"destructive"' is not assignable …. Use colorScheme="danger" / "success" / "neutral" etc. instead. If a different preset was chosen, check components/ui/badge.tsx before assuming the variant contract.

  5. Install the test stack (required for every harness run — the quickstart does not ship a test runner). Drop-in templates live at assets/test-stack/:

    npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom @vitejs/plugin-react
    

    Copy assets/test-stack/vitest.config.ts and assets/test-stack/vitest.setup.ts into the project root next to package.json. Add scripts to package.json and the tsconfig.json types patch — both documented in assets/test-stack/README.md. The tsconfig.json types patch is non-optional: without it tsc --noEmit fails on every test file with Cannot find name 'expect' / 'vi' / 'describe'.

    For typed SDK stubs (client.query / mutate / subscribe / destroy), follow the vi.fn<Signature>() pattern in the marketplace-sdk-client skill, § 9 — naked vi.fn() fails tsc --noEmit.

    Next 16 client-only value detection — the scaffold targets Next 16, which ships a new react-hooks/set-state-in-effect lint rule. Patterns like useEffect(() => setFoo(detect()), []) (a common way to fetch client-only values such as window.parent !== window.self after hydration) now fail lint. Use useSyncExternalStore instead. A drop-in template — with the two non-obvious rules baked in (referentially-stable snapshots cached at module scope, no-op subscribe) — lives at assets/use-sync-external-store-template.tsx. Copy it into lib/embedding.ts (or equivalent) and use the exported useEmbedding() hook from any component. Load-bearing for any harness that needs to distinguish "iframed in portal" vs "top-level browser" at runtime. Live-verified 2026-04-21.

  6. npm run typecheck, npm run lint, npm run build, and npm run test to validate the scaffold's own code + test stack wiring.

  7. Map extension points to routes — invoke the marketplace-sdk-extension-routes skill interactively with the user. The scaffold ships only app/page.tsx; each extension point the app exposes (Standalone / Full screen / Dashboard widgets / Page context panel / Custom field) needs its own app/<route>/page.tsx. Dashboard widgets may have multiple routes.

  8. If you kept the nested next-app/ layout (skipped the flatten in step "Flatten the next-app/ subdirectory" above) — pin turbopack.root in next.config.mjs. Next 16's Turbopack auto-infers the project root by walking up from the route file (app/...); in a nested <repo>/site/next-app/ layout it picks app/ as the workspace root, which makes CSS resolution for @import "tailwindcss" (and tw-animate-css) walk up from site/ and miss next-app/node_modules/. Symptom in the dev console:

    Error: Can't resolve 'tailwindcss' in 'C:\...\<repo>\site'
    Next.js inferred your workspace root, but it may not be correct.
    

    Fix in next.config.mjs:

    const nextConfig = {
      turbopack: {
        root: import.meta.dirname,
      },
      // ...rest
    };
    

    Discovered while rebuilding a Marketplace app (2026-05-02). If you applied the flatten (so the app root IS site/), this pin is not needed.

  9. Before portal install (real iframe testing) — add Chrome Local Network Access headers to the Next config. The portal is served from a public origin (https://app.sitecorecloud.io); Chrome's Local Network Access policy blocks public-origin iframes from loading localhost URLs unless the target advertises consent. A drop-in config lives at assets/next-config-pna-headers.mjs — copy it verbatim, or merge its headers() block into the config you already have.

    ⚠️ The quickstart now emits next.config.ts, not next.config.mjs, and it is EMPTY apart from import type { NextConfig } (verified against the live registry 2026-08-23). So there is nothing to merge into — but do not drop the .mjs asset in alongside it, because Next resolves only one config file and the two silently compete. Port the headers() block into the existing .ts:

    import type { NextConfig } from "next"
    
    const nextConfig: NextConfig = {
      async headers() {
        return [{
          source: "/:path*",
          headers: [
            { key: "Access-Control-Allow-Private-Network", value: "true" },
            { key: "Access-Control-Allow-Origin", value: "*" },
            { key: "Access-Control-Allow-Methods", value: "GET, POST, PUT, DELETE, OPTIONS" },
            { key: "Access-Control-Allow-Headers", value: "Content-Type, Authorization, Access-Control-Request-Private-Network" },
          ],
        }]
      },
    }
    
    export default nextConfig
    

    Verify it rather than assuming — a missing header presents as a blank iframe, which is indistinguishable from a crashed app and from an app that was registered but never installed:

    curl -sD - -o /dev/null http://localhost:3000/ | grep -i access-control-allow-private-network
    

    Do not combine Access-Control-Allow-Origin: * with Access-Control-Allow-Credentials: true — the spec forbids that combo; browsers silently reject the response. For iframe-embed navigation, credentials aren't needed (cookie credentialing uses SameSite / Secure on the cookies themselves, not CORS). The asset file documents this trap inline.

    HTTP is fine for Mode A — the app sets no cookies at its own origin; auth is portal-brokered via postMessage. No HTTPS, no mkcert, no cert-trust dance required for client-side apps. HTTPS + mkcert applies only to the full-stack variant (cookies at the app origin) — see setup-marketplace-full-stack.

    Mode A apps need no .env.local — portal brokers auth. Env vars enter the picture only for Mode B experimental server-to-server (see the marketplace-sdk-lifecycle skill, § 5b).

  10. npm run dev to start locally (HTTP is fine — see step 9).

Optional: server-side OAuth proxy for direct Sitecore REST calls

Apply this section if the app needs to call a Sitecore REST API directly (Agent /screenshot, Pages, Publishing, Sites) because the Marketplace SDK has no wrapper for the endpoint you need. Do not apply if the SDK already exposes the call — see the "SDK-first rule" above.

This is the lean alternative to the full-stack scaffold for service-to-service REST proxies. You keep the client-side scaffold (Mode A postMessage bridge for the SDK side) and add one Node-runtime route handler that holds the client_secret and brokers the OAuth client_credentials flow.

When this is correct (vs full-stack scaffold)

You have…Use this sectionUse full-stack scaffold
A Sitecore REST endpoint with no SDK wrapper, called server-to-server with your own client_id/client_secret✅❌ (dead Auth0 weight)
A logged-in Cloud Portal user; server makes XMC calls via experimental_createXMCClient on their behalf❌✅
Both of the above in one app✅ apply both✅ (Auth0 PKCE for user routes + this proxy for server-to-server routes)
Webhook handler / scheduled job / no logged-in user in the loop✅❌

A page-screenshot app is the typical example of the proxy pattern: postMessage subscribe (Mode A) for page-context awareness + a single OAuth client_credentials proxy for the SitecoreAI Agent /screenshot REST call.

Steps

  1. Get an automation client from Cloud Portal. Cloud Portal → Settings → Automation Clients → New. Pick the API the client should authorize against (Agent, Pages, Publishing, Sites). You receive a client_id and a client_secret. Treat the secret like a password — never commit, never NEXT_PUBLIC_*.

  2. Add server-only env vars to .env.local using the three-segment naming convention from sitecoreai-auth § 0a:

    # .env.local — server-only (NO NEXT_PUBLIC_ prefix)
    SITECORE_<PURPOSE>_CLIENT_ID=...
    SITECORE_<PURPOSE>_CLIENT_SECRET=...
    

    <PURPOSE> is a short uppercase token describing why this client exists in your app (e.g. DEPLOY for general Agent automation, AI for brand-review skills, PUBLISH for publishing jobs). The convention lets one app carry multiple automation clients side-by-side without collision.

  3. Add a Node-runtime route handler at app/api/<purpose>/route.ts (or app/api/<purpose>/[param]/route.ts for parameterized endpoints). Mandatory:

    export const runtime = "nodejs"; // Edge cannot reliably hold the token cache;
                                     // SitecoreAI auth + REST endpoints live outside the Edge network
    

    The route is the single chokepoint for: token acquisition + cache, OAuth retry/backoff, error normalization. The browser calls the same-origin path (fetch('/api/<purpose>/...')) — never auth.sitecorecloud.io or edge-platform.sitecorecloud.io directly.

  4. Implement the OAuth client_credentials flow inside the route following sitecoreai-auth:

    • § 0 — credential-acquisition protocol
    • § 0a — three-segment env-var naming
    • § 5 — token cache pattern (in-memory; cache by sub claim if you carry multiple clients)
    • § 6 — header format (Authorization: Bearer <jwt>)
    • § 7 — 401 handling (invalidate + retry once)

    For Agent-API specifics use sitecoreai-agent; for Pages, Publishing, Sites use the corresponding sitecoreai-* skill.

  5. Return a uniform JSON envelope. Recommended shape: { ok: true, data } or { ok: false, error: { code, message } } at HTTP 200 in both cases (so the browser fetch never throws on !response.ok). A route such as app/api/screenshot/[pageId]/route.ts is the typical place for it.

  6. Do NOT flip the dev script to HTTPS, do NOT install Auth0 PKCE. This proxy sets no cookies at the app origin (the browser does not authenticate to your server — your server authenticates to Sitecore). HTTP localhost remains fine, the Chrome PNA header block from step 9 of the main scaffold is sufficient. No mkcert -install needed for this pattern alone.

  7. Browser caller pattern. From any client component:

    const res = await fetch(`/api/<purpose>/${param}`);
    const envelope = await res.json();
    if (envelope.ok) { /* use envelope.data */ } else { /* surface envelope.error */ }
    

Forbidden in the proxy pattern

ShortcutWhy
Putting client_id / client_secret under NEXT_PUBLIC_*Inlines the secret into the client bundle; full credential leak.
Calling auth.sitecorecloud.io from the browserSame — exposes the secret. The browser must call your same-origin route, full stop.
Using Edge runtime for the routeEdge cannot reliably hold the in-memory token cache; refresh storms result. Stick with runtime = "nodejs".
Reaching for full-stack scaffold to "get the route capability"The route capability is one file plus an env var; you do not need Auth0 PKCE, @auth0/auth0-react, the four-prompt env chain, or HTTPS-mkcert. Adopting them anyway carries unused surface area into code review forever.
Hand-rolling a second OAuth flow when SDK already exposes the callRe-read the SDK-first rule. If xmc.* / ai.* covers it, use the SDK over postMessage. The proxy is only for genuinely SDK-less endpoints.

Forbidden shortcuts

ShortcutWhy
Hand-installing @sitecore-marketplace-sdk/* deps without the shadcn quickstartMisses the MarketplaceProvider, hooks, and example components — re-creating them by hand drifts from the canonical shape.
Skipping the next-app/ flatten when the project's app root is meant to be site/Forces a site/next-app/ prefix on every downstream path; pure overhead.
Skipping the lint fixes (P-019 typo + apostrophe)npm run lint fails out of the box; CI breaks before any feature work.
Skipping the Vitest config + tsconfig types patchRED tests can't compile; harness runs are blocked.
Trying HTTPS-mkcert flow for Mode AUnnecessary complexity; HTTP + PNA headers are sufficient. The HTTPS flow exists for the full-stack variant only.
Picking the full-stack scaffold just to add a single OAuth REST proxyCarries unused Auth0 PKCE / @auth0/auth0-react / four-prompt env chain / HTTPS-mkcert. Use the "Optional: server-side OAuth proxy" section above instead.

What runs after this skill

  • marketplace-sdk-extension-routes — pick Cloud Portal extension points and generate route files
  • marketplace-sdk-client — Client SDK API reference (init, query/mutate/subscribe)
  • marketplace-sdk-xmc — XMC endpoints if the app reads/writes SitecoreAI data
  • sitecoreai-auth (only if applying the "Optional: server-side OAuth proxy" section) — credential acquisition, three-segment env-var naming, token cache, header format, 401 handling
  • sitecoreai-agent / sitecoreai-pages / sitecoreai-publishing / sitecoreai-sites — endpoint reference for whichever Sitecore REST API the proxy calls
  • marketplace-sdk-testing-debug — local dev loop, iframe debugging, runtime-value capture
  • blok-setup + blok-components — Blok design system (default UI layer for Marketplace apps)

Marketplace Full-Stack Integration Scaffold

Use when: Building a Marketplace app that needs server-side SDK calls on behalf of a logged-in Cloud Portal user — typically experimental_createXMCClient invoked from SSR, server actions, or API routes that act as the user. The auth flow is Auth0 PKCE (Mode B): a real user logs into the portal, the iframe gets an access token, your server calls XMC with that token.

Do NOT use when: the app's only server-side need is a direct Sitecore REST API call (Agent / Pages / Publishing / Sites) issued with your own automation client_id + client_secret because the SDK has no wrapper for that endpoint. That is Mode C — service-to-service, and the lighter shape is setup-marketplace-client-side + its "Optional: server-side OAuth proxy" section. Picking this scaffold for that case carries unused Auth0 PKCE / @auth0/auth0-react / four-prompt env chain / HTTPS-mkcert into your app forever.

If you haven't decided yet whether this is the right scaffold, run setup-scaffold first. The decision tree distinguishes Mode A (no server), Mode B (this skill), and Mode C (client-side + OAuth proxy).

SDK-first rule

Before committing to this scaffold: confirm the call you need on the server is not already covered by a non-server SDK path. If xmc.* / ai.* / application.* over the postMessage bridge can do the job from the browser (Mode A), do that — setup-marketplace-client-side is the right scaffold and you avoid the entire Auth0 / HTTPS / mkcert chain. The full-stack scaffold only earns its keep when the server must be the one calling SDK endpoints (typically because the call needs to happen during SSR, in a Server Action, or via experimental_createXMCClient with a user's token).

Canonical command

Interactive:

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

Non-interactive (agents / CI):

yes '' | npx --yes shadcn@latest add https://blok.sitecore.com/r/marketplace/next/quickstart-with-full-stack-xmc.json --yes --cwd <absolute-target-path>

Interactive prompts

Identical to the client-side variant — same four, same defaults Next.js / next-app / Radix / Nova. The non-interactive form above works unchanged.

Output layout — the scaffold creates a next-app/ subdirectory, not in-place

<target>/
└── next-app/
    ├── package.json                           # + @auth0/auth0-react added (Mode B dep)
    ├── .env.local                             # NEXT_PUBLIC_AUTH0_* + SITECORE_* placeholders populated
    ├── next.config.ts                         # CSP frame-ancestors allowlist (populated)
    ├── next.config.mjs                        # ⚠ empty leftover from the template — DELETE
    ├── app/
    │   ├── layout.tsx                         # wraps MarketplaceProvider + AuthProvider
    │   ├── page.tsx                           # demo landing
    │   └── api/sites/languages/route.ts       # Mode B Route Handler worked example
    ├── components/
    │   ├── providers/
    │   │   ├── marketplace.tsx                # Mode A provider (still ships — Mode A + B coexist)
    │   │   └── auth.tsx                       # NEW — Auth0 React provider + useAuth() helper
    │   └── examples/
    │       ├── built-in-auth/                 # Mode A examples (same as the client-side variant)
    │       └── custom-auth/                   # NEW — Mode B examples
    │           ├── with-api-route/list-languages.tsx
    │           └── with-server-action/
    │               ├── list-languages.tsx
    │               └── action.ts
    ├── hooks/
    └── lib/

The next-app/ flatten guidance from the client-side variant applies here too — see the setup-marketplace-client-side skill for the flatten command and rationale; the trade-off is identical.

What it creates

  • Everything the client-side variant creates PLUS:
  • @auth0/auth0-react added to deps — PKCE public-client OAuth, no client secret needed
  • AuthProvider wrapping Auth0Provider + withAuthenticationRequired; useAuth() hook augments getAccessTokenSilently with org/tenant authorization params
  • Pre-written Mode B worked examples — experimental_createXMCClient calls via both API Route Handler and Server Action
  • next.config.ts with Content-Security-Policy: frame-ancestors 'self' https://marketplace-app.sitecorecloud.io https://pages.sitecorecloud.io https://xmapps.sitecorecloud.io — good security default the client-side variant doesn't have

Characteristics

  • Mode B (Auth0 PKCE — user-delegated tokens on the server) for secure server-side XMC calls
  • Mode A (portal-brokered iframe SDK) still available via MarketplaceProvider — both can be used in the same app
  • Suited for: full applications, portals with auth, integrations requiring secure server-side XMC access, management tools that need to call XMC with a user's access token

Auth modes — confirm Mode B before running this scaffold

This scaffold is the Mode B (Auth0 PKCE) path. Below is the full picture; only the middle row belongs in this skill.

Auth flowScaffoldUse when
Mode A — portal-brokered postMessagesetup-marketplace-client-sideAll needed calls live in the SDK (xmc.*, ai.*, application.*); no server side at all
Mode B — Auth0 PKCE (user-delegated server SDK calls)This skillLogged-in Cloud Portal user; server makes SDK calls as them via experimental_createXMCClient (SSR / server actions / API routes that act on the user's behalf)
Mode C — OAuth 2.0 client-credentials (server-to-server REST proxy)setup-marketplace-client-side + its "Optional: server-side OAuth proxy" sectionServer-to-server calls to a Sitecore REST API (Agent / Pages / Publishing / Sites) with your own client_id + client_secret, because the SDK has no wrapper for that endpoint. No logged-in user in the loop.

Mode C does NOT belong in this scaffold — redirect

If your only server-side need is a Sitecore REST proxy with client_credentials, stop and switch to setup-marketplace-client-side. Apply its "Optional: server-side OAuth proxy" section: one Node-runtime route handler, two server-only env vars (SITECORE_<PURPOSE>_CLIENT_ID/SECRET), no PKCE, no HTTPS-mkcert, no four-prompt env chain. Reference sitecoreai-auth for the OAuth flow.

A cautionary example (a page-screenshot app, 2026-05-02). It picked this scaffold (full-stack) just to land one Node route for the SitecoreAI Agent /screenshot REST proxy — and now carries the unused Auth0 PKCE / @auth0/auth0-react / custom-auth/ examples / four-prompt env chain forever. The correct shape would have been setup-marketplace-client-side + the OAuth proxy section.

Hybrid (Mode B + Mode C in one app)

If you genuinely need both user-delegated server SDK calls and server-to-server REST proxies (e.g. a portal-with-auth that also runs background SitecoreAI REST jobs): use this scaffold for Mode B and also apply the OAuth-proxy steps from setup-marketplace-client-side's optional section for the Mode C routes. Auth0 PKCE for the user-facing routes; client-credentials for the background/proxy routes. Two token caches, two sets of env vars, no overlap. This is the only case where mixing belongs in the full-stack scaffold.

Post-scaffold steps

  1. cd <target>/next-app — all subsequent commands run inside the next-app/ subdirectory.

  2. Delete the leftover empty next.config.mjs — the scaffold ships BOTH next.config.mjs (empty) and next.config.ts (populated with CSP). Next 15+ picks up .ts, so the .mjs is dead weight; first-time builder patching the empty .mjs thinking it's authoritative will scratch their head when headers don't land. rm next-app/next.config.mjs.

  3. Apply the same lint fixes to components/providers/marketplace.tsx — this scaffold ships the same provider file as the client-side variant with the same extention typo + unescaped-apostrophe lint failures. Fix both before npm run lint: (a) extention → extension, (b) your app's → your app&apos;s.

  4. Install the test stack — Vitest + testing-library + jsdom + plugin-react + the tsconfig.json types patch ("types": ["vitest/globals", "@testing-library/jest-dom"]). The quickstart doesn't ship a test runner. Drop-in templates (vitest.config.ts, vitest.setup.ts, install command, scripts, types patch) live at the setup-marketplace-client-side skill's assets/test-stack/ — same files apply here unchanged.

5a. If you kept the nested next-app/ layout (skipped the flatten) — pin turbopack.root in next.config.ts. Same Next 16 workspace-root inference bug as the client-side variant: Turbopack picks app/ as the project root and CSS resolution for @import "tailwindcss" walks up from site/, missing next-app/node_modules/. Symptom: Error: Can't resolve 'tailwindcss' in 'C:\...\<repo>\site'. Fix in next.config.ts:

const config: NextConfig = {
  turbopack: {
    root: import.meta.dirname,
  },
  // ...rest
};

Discovered while rebuilding a Marketplace app (2026-05-02); see also the parallel section in setup-marketplace-client-side step 8. If you applied the flatten (so the app root IS site/), this pin is not needed.

  1. Merge Chrome PNA headers into next.config.ts alongside the shipped CSP frame-ancestors allowlist. This scaffold ships the CSP but not the Local Network Access consent — without the PNA headers Chrome will still block public-origin iframes (portal → localhost) even over HTTPS. The four-header block lives at the setup-marketplace-client-side skill's assets/next-config-pna-headers.mjs; never combine Access-Control-Allow-Origin: * with Access-Control-Allow-Credentials: true (the spec forbids it and browsers silently reject the response; iframe navigation needs no credentials header). Keep your existing CSP headers entry — append the four PNA headers to the same headers array of the same source: "/(.*)" rule.

  2. Flip the dev script to HTTPS. This scaffold is full-stack Mode B: the app sets Secure; SameSite=None cookies at its own origin during the Auth0 flow, which requires HTTPS locally. Edit package.json → scripts.dev to next dev --experimental-https --turbopack. On Windows, also run mkcert -install once from an elevated PowerShell so the cert is system-trusted — otherwise iframe cert rejection produces chrome-error://chromewebdata/ in the portal. Without admin rights, pre-generate the cert instead (mkcert -key-file certificates/localhost-key.pem -cert-file certificates/localhost.pem localhost 127.0.0.1 ::1; Next reuses it and skips -install) — but an untrusted cert still fails inside the portal iframe, so either get the CA trusted or tunnel (cloudflared / ngrok) and register the tunnel URL. After regenerating a cert, fully restart Chrome: it caches trust per process. Deeper debugging: the marketplace-sdk-testing-debug skill.

  3. Populate .env.local — interactive prompt chain (do not leave placeholders). The scaffold pre-adds eight NEXT_PUBLIC_* vars. Four already have correct defaults (AUTH0_DOMAIN, AUTH0_AUDIENCE, AUTH0_SCOPE, APP_BASE_URL) — leave them alone. Four need real values. Ask the user for each one verbatim — do not assume or skip. Leaving placeholders produces a silent access_denied redirect loop the first time the app loads in the portal iframe, with error Product codes in request do not match client Product codes. (AUTH-APL50-56).

    Before prompting — offer the "use defaults" shortcut. If a project-local .env ships working Marketplace-app defaults (matching .env.local names one-to-one), ask the user first:

    Do you want to provide the four Marketplace values yourself, or use the defaults from the project's root .env? (type use default to copy them automatically, or provide to enter each one)

    If the user answers use default (or equivalent: "default", "defaults", "yes use defaults"): read the root .env, copy the values for NEXT_PUBLIC_AUTH0_CLIENT_ID, NEXT_PUBLIC_SITECORE_APP_ID, NEXT_PUBLIC_SITECORE_ORGANIZATION_ID, and NEXT_PUBLIC_SITECORE_TENANT_ID into the new app's .env.local, and skip prompts 7a–7d. Report which values were copied (mask nothing — these are public PKCE identifiers, see note at end of this step).

    If the user answers provide (or anything other than a clear "use default"): continue with prompts 7a–7d below.

    Prompt the user for these four values, in this order, with these exact questions:

    Prompt 7a — NEXT_PUBLIC_AUTH0_CLIENT_ID

    What is your Auth0 Client ID for this Marketplace app? Where to find: Cloud Portal → App Studio → your app → General / Auth0 section. Looks like a 32-char alphanumeric string (e.g. AbCdEfGhIjKlMnOpQrStUvWxYz012345). This identifies the OAuth client registered for your app; wrong value causes Auth0 to reject with unauthorized_client.

    Prompt 7b — NEXT_PUBLIC_SITECORE_APP_ID

    What is your Sitecore App ID for this Marketplace app? Where to find: Cloud Portal → App Studio → your app → Overview (labelled "App ID" or "Client ID"). A UUID like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. The AuthProvider derives product_codes: mkp_${APP_ID}; if this value doesn't match the app Auth0 has registered, every authorization request fails with error AUTH-APL50-56 "Product codes in request do not match client Product codes" and withAuthenticationRequired loops. This is the #1 silent-failure trap.

    Prompt 7c — NEXT_PUBLIC_SITECORE_ORGANIZATION_ID

    What is your Cloud Portal Organization ID? Where to find (two easy paths):

    • Portal iframe URL (fastest): once the app is installed and the portal loads the iframe, the iframe src= includes ?organizationId=org_… as a query parameter. Copy that exact value (starts with org_, ~20 chars, e.g. org_<your-org-id>).
    • Cloud Portal UI: organization switcher → Settings → Organization → Organization ID.

    Prompt 7d — NEXT_PUBLIC_SITECORE_TENANT_ID

    What is your Marketplace app tenant ID (assigned after install)? Where to find: the same portal iframe URL from 7c also includes ?marketplaceAppTenantId=… — a UUID like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. That's this value. If the app is not yet installed into a SitecoreAI environment, this value doesn't exist yet — install first, then grab it from the iframe URL after reload.

    After the four prompts: write the values into .env.local, preserving the four defaults, save, hard-reload the portal tab.

    Why all vars are NEXT_PUBLIC_* — PKCE public-client OAuth means there is no client secret. Identifiers (domain, audience, client ID, org/tenant, app ID) are public by design; they're embedded in the client bundle because the authorization flow happens browser-side. This is not a secret-leak, it's the PKCE flow. Background in the marketplace-sdk-lifecycle skill, § 5b + § 5c.

    If the user can't find a value — do NOT guess or substitute; ask them to open App Studio / the portal iframe URL and report what they see. Wrong values here create failure modes that look like configuration bugs elsewhere (iframe hangs, Auth0 redirects, CSP errors) and waste hours to diagnose.

  4. Pick a canonical response-unwrap convention for your Mode B examples. The two shipped examples are inconsistent: the Server Action unwraps at the server (return languages?.data ?? [] → client receives Xmapp.Language[]), while the API Route passes the full SDK wrapper (NextResponse.json(languages)) and the client unwraps (setLanguages(data.data)). Same backend call, two client contracts. Recommendation: unwrap at the server boundary always — Server Action and Route Handler both do return languages?.data ?? [] so consumers always receive Xmapp.Language[]. Pick one and commit; document the choice in the ADR.

  5. npm run typecheck, npm run lint, npm run build, and npm run test to validate the scaffold's own code + your patches.

  6. npm run dev to start locally (HTTPS on port 3000 after step 6).

Forbidden shortcuts

ShortcutWhy
Hand-assembling Auth0 + PKCE config without the shadcn quickstartEasy to misconfigure product_codes / audience / tenant_id and trip AUTH-APL50-56.
Skipping the next.config.mjs deletionFirst-time builders patch the empty .mjs thinking it's authoritative; headers don't land.
Skipping the HTTPS dev-script flipAuth0 cookies (Secure; SameSite=None) cannot be set over HTTP; auth silently fails.
Skipping mkcert -install on WindowsSelf-signed cert rejected inside iframe → chrome-error://chromewebdata/.
Leaving .env.local placeholdersSilent access_denied redirect loop with AUTH-APL50-56 on first portal load.
Mixing the two response-unwrap conventionsSame backend call returns different shapes to different consumers.

What runs after this skill

  • marketplace-sdk-extension-routes — pick Cloud Portal extension points and generate route files
  • marketplace-sdk-lifecycle — Auth0 model, hosting, custom-vs-public app
  • marketplace-sdk-client — Client SDK API reference (Mode A coexists with Mode B in this app)
  • marketplace-sdk-xmc — XMC endpoints in both Mode A and Mode B (experimental_createXMCClient)
  • marketplace-sdk-ai — AI skills if the app uses brand review
  • marketplace-sdk-testing-debug — local dev loop, iframe cookie config, mkcert traps, debugging checklist
  • blok-setup + blok-components + blok-marketplace-integration — Blok design system

Sitecore Project Scaffolding — Decision Tree

This skill is the entry point for any greenfield Sitecore project. It picks the right scaffold variant; the routed setup-* skill owns the actual commands, failure policy, and post-scaffold steps.

When to use

  • A greenfield Sitecore project is being started and no rendering host exists yet
  • A PRD or design doc identifies that a new head application is needed
  • The user asks for a new project based on Content SDK, SitecoreAI, SitecoreAI (head app / headless site / rendering host), head application, editing host, or related wording
  • The project brief mentions Content SDK, SitecoreAI, or a Marketplace integration

Do not scaffold into an existing project. If a rendering host is already present, read its structure and extend it — do not re-scaffold.


SDK-first rule (read before the decision tree)

If the Marketplace SDK exposes the call you need (xmc.*, ai.*, application.*), use the SDK — never reach for a direct Sitecore REST API call. The SDK runs over the postMessage bridge (Mode A) and handles auth for you; bypassing it for an endpoint that already has a wrapper is a mistake.

A direct REST call against a Sitecore API (Agent / Pages / Publishing / Sites — issued with your own OAuth client_credentials) is only justified when the SDK has no wrapper for the endpoint you need. When that happens, you get a client_id + client_secret from Cloud Portal → Automation Clients and you do the OAuth dance yourself server-side.

Crucially: needing a direct REST call by itself does NOT push you to the full-stack scaffold. It only means you need one Node-runtime route handler to hold the client_secret. The client-side scaffold + a single route handler is the right shape — see the "Optional: server-side OAuth proxy" section in setup-marketplace-client-side. The full-stack scaffold is for user-delegated server-side SDK calls (Auth0 PKCE + experimental_createXMCClient), not for service-to-service REST proxies.

Decision tree

Is the project a Marketplace integration?
│
├─ NO  → Is it a standard SitecoreAI headless rendering host?
│        └─ YES → use setup-content-sdk
│
└─ YES → Do you need server-side SDK calls (SSR, server actions, experimental_createXMCClient
         on behalf of a logged-in Cloud Portal user)?
         │
         ├─ YES → use setup-marketplace-full-stack
         │        (Auth0 PKCE — user-delegated tokens; Mode B)
         │
         └─ NO  → Will the app call any Sitecore REST API directly (Agent / Pages /
                  Publishing / Sites) because the SDK has no wrapper for it?
                  │
                  ├─ NO  → use setup-marketplace-client-side
                  │        (pure Mode A — postMessage bridge only)
                  │
                  └─ YES → use setup-marketplace-client-side AND add a single
                           Node route handler for the OAuth client-credentials proxy.
                           See its "Optional: server-side OAuth proxy" section, plus
                           sitecoreai-auth for the OAuth flow + token cache.
                           Do NOT use the full-stack scaffold — the Auth0 PKCE surface
                           area is dead weight in this case (one screenshot app carries
                           this for good; the client-side + proxy shape is correct).

Routed skills

If the answer is…Invoke this skillCanonical command
Content SDK head app (SitecoreAI rendering host)setup-content-sdknpx create-content-sdk-app@latest --template nextjs-app-router (App Router — the default; the bare nextjs token gives Pages Router and is NOT interchangeable — see setup-content-sdk STEP 0, then verify src/app/ exists; --template nextjs-app-router-cache-components when publishes must go live without a redeploy — STEP 0b)
Marketplace Client-Side (browser-only widget / UI extension / embedded app)setup-marketplace-client-sidenpx shadcn@latest add https://blok.sitecore.com/r/marketplace/next/quickstart-with-client-side-xmc.json
Marketplace Client-Side + OAuth proxy for direct Sitecore REST callssetup-marketplace-client-side (same scaffold) + its "Optional: server-side OAuth proxy" sectionClient-side quickstart above + one hand-written app/api/<purpose>/route.ts
Marketplace Full-Stack (server-side SDK calls on behalf of a logged-in user — Auth0 PKCE + experimental_createXMCClient)setup-marketplace-full-stacknpx shadcn@latest add https://blok.sitecore.com/r/marketplace/next/quickstart-with-full-stack-xmc.json

Each routed skill carries the canonical command, failure policy, forbidden shortcuts, and the full post-scaffold step list. Do not run the commands from this skill — invoke the routed skill so the consumer receives the up-to-date post-scaffold guidance for the variant they picked.


How to disambiguate the user's intent (when the brief is vague)

If the brief says "new Sitecore app" without naming a variant, ask one clarifying question before routing:

Which kind of Sitecore app are you building?
  (a) A SitecoreAI rendering host (a public-facing headless website driven by SitecoreAI)
  (b) A Marketplace app — embedded inside the Sitecore Cloud Portal as a widget / panel / full-screen tool
      (b1) Client-side only — postMessage SDK only (Mode A); no server routes
      (b2) Client-side + OAuth proxy — Mode A SDK + ONE Node route handler that calls
           a Sitecore REST API directly (Agent / Pages / Publishing / Sites) using your
           own client_id + client_secret, because the SDK has no wrapper for that endpoint
      (b3) Full-stack — server-side SDK calls on behalf of a logged-in Cloud Portal user
           (Auth0 PKCE + experimental_createXMCClient; e.g. SSR or server actions that
           act as the logged-in user)

The answer maps 1:1 to the routed skills (b2 routes to the same scaffold as b1 — just with the optional OAuth-proxy section applied). Do not guess — getting this wrong forces a re-scaffold later.

Heuristic for b2 vs b3: if the user mentions "automation client", "client_id + client_secret", "service-to-service", "webhook handler", "scheduled job", or names a SitecoreAI REST endpoint (Agent /screenshot, Pages, Publishing, Sites) — that's b2, not b3. b3 is for apps where a real human is logged in and the server makes SDK calls as them.


Forbidden across all three variants

These shortcuts produce drift, so they are forbidden by every routed skill:

ShortcutWhy it's forbidden
Cloning solo-website / SitecoreAI starter as a substituteNot the official generator; couples you to starter layout instead of CLI defaults.
Copying another local app as a "template"Drifts from current CLI defaults and hides updates.
npm init + pasted @sitecore-content-sdk/* or @sitecore-marketplace-sdk/* depsEasy to miss middleware, proxy, component maps, and config the CLI sets up.
Hand-assembling the Auth0 / Cloud Portal registration valuesThe full-stack variant has a documented prompt chain — using it prevents AUTH-APL50-56 redirect loops.

Exception: Only when the user explicitly asks for a named starter (e.g. "use the SitecoreAI starter solo-website repo because…"). Document the override in the project's ADR.


Agent guidance

When a PRD or architecture calls for a new Sitecore rendering host or Marketplace integration:

  1. Run this skill first to identify which scaffold applies. Record the choice as an architectural commitment (e.g. an ADR).
  2. Invoke the routed setup-* skill for the actual scaffold command and post-scaffold steps.
  3. Reference the routed skill in the implementation plan's stack/tooling section so the implementing agent has the exact command without having to re-run the decision tree.
  4. Run the scaffold as the first implementation step. Do not scaffold if a rendering host already exists.

For any greenfield Sitecore app, this is the entry skill — the routed skill carries the variant-specific detail.

Sponsors

Details

Marketplace
Chris1415/sitecore-skills-pocs
Source
plugins/sitecore-setup
Category
Sitecore
License
Apache-2.0

More from Chris1415/sitecore-skills-pocs

All 8