
sitecore-setup
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-pocsRun it inside Claude Code after adding the marketplace with /plugin marketplace add Chris1415/sitecore-skills-pocs.
Contents
Discovered from sourceSkills 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-flowskill (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 needed | Template id | Post-scaffold proof |
|---|---|---|
| App Router | nextjs-app-router | src/app/ exists, src/pages/ does not |
| App Router + on-demand revalidation (OSR) | nextjs-app-router-cache-components | as above, plus src/app/api/revalidate/route.ts exists and next.config.* sets cacheComponents: true |
| Pages Router | nextjs | src/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
nextjstoken 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:
@latestwith the sitewide purge, or@<exact canary version>fromnpm view create-content-sdk-app dist-tags.canary. Never pin a canary silently, and never use the floating@canarytag.
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
| Shortcut | Why |
|---|---|
solo-website / SitecoreAI starter clone or degit | Not 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/* deps | Easy 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 generatedpackage.jsonfor 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
-
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.localI 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— usuallyen*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_SECRETsilently breaks preview/editing with confusing 401 errors at the end of the build — this value must come from the user. -
Run
dotnet sitecore loginto authenticate with SitecoreAI (when using CLI against CM). -
Run
dotnet sitecore ser pushto push serialized items to CM (when applicable). -
Run
npm run devornpm run start:connectedin 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-sideorsetup-marketplace-full-stackinstead
Greenfield checklist
- Picked the template by router (STEP 0) —
--template nextjs-app-routerfor App Router (the default for new work), barenextjsonly 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 andsrc/pages/does not (Pages Router: the reverse). Cache-components:src/app/api/revalidate/route.tsexists andcacheComponents: trueis 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.localexists with the required Edge context values sonpm run devcan resolve Edge context and API key. - Post-scaffold: Edge / editing /
sitecore.config.tsfollow 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 thesitecore-content-sdk-nextjs-pages-routerplugin (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:
| Prompt | Default | Recommended |
|---|---|---|
| Start a new project? (framework) | Next.js | Next.js |
| What is your project named? | next-app | Accept default unless renaming |
| Select a component library | Radix | Radix |
| 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/xmcpre-installed components/providers/marketplace.tsx—MarketplaceProvider+useMarketplaceClient+useAppContexthooks (React Context pattern — the scaffold's canonical SDK init shape, see themarketplace-sdk-clientskill, § 2)components/examples/built-in-auth/— working example components forapplication.contextquery + XMClistLanguagesquery (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-lifecycleskill, § 5a) - Suited for: dashboards, editors, lightweight portals, UI extensions
Post-scaffold steps
-
cd <target>/next-app— all subsequent commands run inside thenext-app/subdirectory. -
Verify
npm installcompleted (shadcn runs it automatically; confirmpackage-lock.jsonexists). -
Review the scaffolded components under
components/(NOTsrc/components/— Next.js 16 quickstart has nosrc/dir). -
Fix scaffold lint nits — the quickstart ships
components/providers/marketplace.tsxwith two small errors that makenpm run lintfail out of the box: (a) typoextention→extension; (b) unescaped apostropheyour app's→your app'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.tsxdoes not use the standard shadcn variant union. Itsvariantis'default' | 'bold'(typography); status/intent is expressed through a separatecolorSchemeprop taking'neutral' | 'primary' | 'success' | 'danger' | 'warning' | …. Code copied from generic shadcn examples (e.g.<Badge variant="destructive">,<Badge variant="secondary">) will failtsc --noEmitwithType '"destructive"' is not assignable …. UsecolorScheme="danger"/"success"/"neutral"etc. instead. If a different preset was chosen, checkcomponents/ui/badge.tsxbefore assuming the variant contract. -
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-reactCopy
assets/test-stack/vitest.config.tsandassets/test-stack/vitest.setup.tsinto the project root next topackage.json. Add scripts topackage.jsonand thetsconfig.jsontypespatch — both documented inassets/test-stack/README.md. Thetsconfig.jsontypes patch is non-optional: without ittsc --noEmitfails on every test file withCannot find name 'expect' / 'vi' / 'describe'.For typed SDK stubs (
client.query/mutate/subscribe/destroy), follow thevi.fn<Signature>()pattern in themarketplace-sdk-clientskill, § 9 — nakedvi.fn()failstsc --noEmit.Next 16 client-only value detection — the scaffold targets Next 16, which ships a new
react-hooks/set-state-in-effectlint rule. Patterns likeuseEffect(() => setFoo(detect()), [])(a common way to fetch client-only values such aswindow.parent !== window.selfafter hydration) now fail lint. UseuseSyncExternalStoreinstead. A drop-in template — with the two non-obvious rules baked in (referentially-stable snapshots cached at module scope, no-opsubscribe) — lives atassets/use-sync-external-store-template.tsx. Copy it intolib/embedding.ts(or equivalent) and use the exporteduseEmbedding()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. -
npm run typecheck,npm run lint,npm run build, andnpm run testto validate the scaffold's own code + test stack wiring. -
Map extension points to routes — invoke the
marketplace-sdk-extension-routesskill interactively with the user. The scaffold ships onlyapp/page.tsx; each extension point the app exposes (Standalone / Full screen / Dashboard widgets / Page context panel / Custom field) needs its ownapp/<route>/page.tsx. Dashboard widgets may have multiple routes. -
If you kept the nested
next-app/layout (skipped the flatten in step "Flatten thenext-app/subdirectory" above) — pinturbopack.rootinnext.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 picksapp/as the workspace root, which makes CSS resolution for@import "tailwindcss"(andtw-animate-css) walk up fromsite/and missnext-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. -
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 loadinglocalhostURLs unless the target advertises consent. A drop-in config lives atassets/next-config-pna-headers.mjs— copy it verbatim, or merge itsheaders()block into the config you already have.⚠️ The quickstart now emits
next.config.ts, notnext.config.mjs, and it is EMPTY apart fromimport type { NextConfig }(verified against the live registry 2026-08-23). So there is nothing to merge into — but do not drop the.mjsasset in alongside it, because Next resolves only one config file and the two silently compete. Port theheaders()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 nextConfigVerify 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-networkDo not combine
Access-Control-Allow-Origin: *withAccess-Control-Allow-Credentials: true— the spec forbids that combo; browsers silently reject the response. For iframe-embed navigation, credentials aren't needed (cookie credentialing usesSameSite/Secureon 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 themarketplace-sdk-lifecycleskill, § 5b). -
npm run devto 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 section | Use 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
-
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_idand aclient_secret. Treat the secret like a password — never commit, neverNEXT_PUBLIC_*. -
Add server-only env vars to
.env.localusing the three-segment naming convention fromsitecoreai-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.DEPLOYfor general Agent automation,AIfor brand-review skills,PUBLISHfor publishing jobs). The convention lets one app carry multiple automation clients side-by-side without collision. -
Add a Node-runtime route handler at
app/api/<purpose>/route.ts(orapp/api/<purpose>/[param]/route.tsfor parameterized endpoints). Mandatory:export const runtime = "nodejs"; // Edge cannot reliably hold the token cache; // SitecoreAI auth + REST endpoints live outside the Edge networkThe route is the single chokepoint for: token acquisition + cache, OAuth retry/backoff, error normalization. The browser calls the same-origin path (
fetch('/api/<purpose>/...')) — neverauth.sitecorecloud.iooredge-platform.sitecorecloud.iodirectly. -
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
subclaim 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 correspondingsitecoreai-*skill. -
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 asapp/api/screenshot/[pageId]/route.tsis the typical place for it. -
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 -installneeded for this pattern alone. -
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
| Shortcut | Why |
|---|---|
Putting client_id / client_secret under NEXT_PUBLIC_* | Inlines the secret into the client bundle; full credential leak. |
Calling auth.sitecorecloud.io from the browser | Same — exposes the secret. The browser must call your same-origin route, full stop. |
| Using Edge runtime for the route | Edge 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 call | Re-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
| Shortcut | Why |
|---|---|
Hand-installing @sitecore-marketplace-sdk/* deps without the shadcn quickstart | Misses 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 patch | RED tests can't compile; harness runs are blocked. |
| Trying HTTPS-mkcert flow for Mode A | Unnecessary 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 proxy | Carries 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 filesmarketplace-sdk-client— Client SDK API reference (init, query/mutate/subscribe)marketplace-sdk-xmc— XMC endpoints if the app reads/writes SitecoreAI datasitecoreai-auth(only if applying the "Optional: server-side OAuth proxy" section) — credential acquisition, three-segment env-var naming, token cache, header format, 401 handlingsitecoreai-agent/sitecoreai-pages/sitecoreai-publishing/sitecoreai-sites— endpoint reference for whichever Sitecore REST API the proxy callsmarketplace-sdk-testing-debug— local dev loop, iframe debugging, runtime-value captureblok-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-reactadded to deps — PKCE public-client OAuth, no client secret neededAuthProviderwrappingAuth0Provider+withAuthenticationRequired;useAuth()hook augmentsgetAccessTokenSilentlywith org/tenant authorization params- Pre-written Mode B worked examples —
experimental_createXMCClientcalls via both API Route Handler and Server Action next.config.tswithContent-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 flow | Scaffold | Use when |
|---|---|---|
| Mode A — portal-brokered postMessage | setup-marketplace-client-side | All needed calls live in the SDK (xmc.*, ai.*, application.*); no server side at all |
| Mode B — Auth0 PKCE (user-delegated server SDK calls) | This skill | Logged-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" section | Server-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
-
cd <target>/next-app— all subsequent commands run inside thenext-app/subdirectory. -
Delete the leftover empty
next.config.mjs— the scaffold ships BOTHnext.config.mjs(empty) andnext.config.ts(populated with CSP). Next 15+ picks up.ts, so the.mjsis dead weight; first-time builder patching the empty.mjsthinking it's authoritative will scratch their head when headers don't land.rm next-app/next.config.mjs. -
Apply the same lint fixes to
components/providers/marketplace.tsx— this scaffold ships the same provider file as the client-side variant with the sameextentiontypo + unescaped-apostrophe lint failures. Fix both beforenpm run lint: (a)extention→extension, (b)your app's→your app's. -
Install the test stack — Vitest + testing-library + jsdom + plugin-react + the
tsconfig.jsontypes 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 thesetup-marketplace-client-sideskill'sassets/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.
-
Merge Chrome PNA headers into
next.config.tsalongside the shipped CSPframe-ancestorsallowlist. 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 thesetup-marketplace-client-sideskill'sassets/next-config-pna-headers.mjs; never combineAccess-Control-Allow-Origin: *withAccess-Control-Allow-Credentials: true(the spec forbids it and browsers silently reject the response; iframe navigation needs no credentials header). Keep your existing CSPheadersentry — append the four PNA headers to the sameheadersarray of the samesource: "/(.*)"rule. -
Flip the dev script to HTTPS. This scaffold is full-stack Mode B: the app sets
Secure; SameSite=Nonecookies at its own origin during the Auth0 flow, which requires HTTPS locally. Editpackage.json→scripts.devtonext dev --experimental-https --turbopack. On Windows, also runmkcert -installonce from an elevated PowerShell so the cert is system-trusted — otherwise iframe cert rejection produceschrome-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: themarketplace-sdk-testing-debugskill. -
Populate
.env.local— interactive prompt chain (do not leave placeholders). The scaffold pre-adds eightNEXT_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 silentaccess_deniedredirect loop the first time the app loads in the portal iframe, with errorProduct codes in request do not match client Product codes. (AUTH-APL50-56).Before prompting — offer the "use defaults" shortcut. If a project-local
.envships working Marketplace-app defaults (matching.env.localnames 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? (typeuse defaultto copy them automatically, orprovideto enter each one)If the user answers
use default(or equivalent: "default", "defaults", "yes use defaults"): read the root.env, copy the values forNEXT_PUBLIC_AUTH0_CLIENT_ID,NEXT_PUBLIC_SITECORE_APP_ID,NEXT_PUBLIC_SITECORE_ORGANIZATION_ID, andNEXT_PUBLIC_SITECORE_TENANT_IDinto 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_IDWhat 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 withunauthorized_client.Prompt 7b —
NEXT_PUBLIC_SITECORE_APP_IDWhat 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. TheAuthProviderderivesproduct_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" andwithAuthenticationRequiredloops. This is the #1 silent-failure trap.Prompt 7c —
NEXT_PUBLIC_SITECORE_ORGANIZATION_IDWhat 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 withorg_, ~20 chars, e.g.org_<your-org-id>). - Cloud Portal UI: organization switcher → Settings → Organization → Organization ID.
Prompt 7d —
NEXT_PUBLIC_SITECORE_TENANT_IDWhat is your Marketplace app tenant ID (assigned after install)? Where to find: the same portal iframe URL from 7c also includes
?marketplaceAppTenantId=…— a UUID likexxxxxxxx-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 themarketplace-sdk-lifecycleskill, § 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.
- Portal iframe URL (fastest): once the app is installed and the portal loads the iframe, the iframe
-
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 receivesXmapp.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 doreturn languages?.data ?? []so consumers always receiveXmapp.Language[]. Pick one and commit; document the choice in the ADR. -
npm run typecheck,npm run lint,npm run build, andnpm run testto validate the scaffold's own code + your patches. -
npm run devto start locally (HTTPS on port 3000 after step 6).
Forbidden shortcuts
| Shortcut | Why |
|---|---|
| Hand-assembling Auth0 + PKCE config without the shadcn quickstart | Easy to misconfigure product_codes / audience / tenant_id and trip AUTH-APL50-56. |
Skipping the next.config.mjs deletion | First-time builders patch the empty .mjs thinking it's authoritative; headers don't land. |
| Skipping the HTTPS dev-script flip | Auth0 cookies (Secure; SameSite=None) cannot be set over HTTP; auth silently fails. |
Skipping mkcert -install on Windows | Self-signed cert rejected inside iframe → chrome-error://chromewebdata/. |
Leaving .env.local placeholders | Silent access_denied redirect loop with AUTH-APL50-56 on first portal load. |
| Mixing the two response-unwrap conventions | Same 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 filesmarketplace-sdk-lifecycle— Auth0 model, hosting, custom-vs-public appmarketplace-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 reviewmarketplace-sdk-testing-debug— local dev loop, iframe cookie config, mkcert traps, debugging checklistblok-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 skill | Canonical command |
|---|---|---|
| Content SDK head app (SitecoreAI rendering host) | setup-content-sdk | npx 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-side | npx 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 calls | setup-marketplace-client-side (same scaffold) + its "Optional: server-side OAuth proxy" section | Client-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-stack | npx 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:
| Shortcut | Why it's forbidden |
|---|---|
Cloning solo-website / SitecoreAI starter as a substitute | Not 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/* deps | Easy to miss middleware, proxy, component maps, and config the CLI sets up. |
| Hand-assembling the Auth0 / Cloud Portal registration values | The 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:
- Run this skill first to identify which scaffold applies. Record the choice as an architectural commitment (e.g. an ADR).
- Invoke the routed
setup-*skill for the actual scaffold command and post-scaffold steps. - 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.
- 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