Plugin's technology stack and architectural choices

The skills produce idiomatic code for a specific, opinionated stack. That opinion is on purpose. It's what lets the agent build a coherent, scalable storefront instead of a pile of plausible-looking fragments that don't fit together. This page spells out the assumptions so you can decide, before you invest, whether they suit your team. If your stack is different, this is the page that tells you where you'll feel it.

The stack at a glance

The thinking behind those choices

• The App Router, rather than the Pages Router, means product and category data is fetched in React Server Components. That keeps the commercetools calls on the server and streams markup to the browser, which is what makes PDP and PLP rendering fast and keeps credentials off the client.

• The single most important rule is the backend-for-frontend (BFF) boundary. The browser never talks to commercetools directly and never sees a credential. Every call goes through a Next.js Route Handler, which calls a helper in lib/ct/, which uses one shared SDK client. No NEXT_PUBLIC_ secrets exist anywhere, ever. The skills enforce this relentlessly, and for good reason.

• That shared SDK client is built once, at module scope, and imported everywhere. Build it per request and you'll exhaust OAuth tokens and leak memory, which is a classic mistake the skills exist to prevent.

• Sessions go in a signed, HTTP-only cookie via jose instead of server-side session storage. No localStorage, which would be exposed to XSS, and no session infrastructure to run. The catch you need to remember is that SESSION_SECRET has to be at least 32 characters in production.
• Tailwind v4 is token-first, with design tokens defined in globals.css and no tailwind.config.ts, which buys you performance and keeps you aligned with where the Next.js ecosystem is heading.
• Product search uses apiRoot.products().search(), the Product Search API. The Product Projection Search API is off the table as it isn't a recommended choice.

• The checkout is owned by commercetools: the payment step mounts the Checkout Browser SDK, which captures payment and creates the order, so the skills deliberately tell the agent not to write a custom payment form or a custom order-creation route.

Where the skills take a stance and where they step back

The agent stays consistent about the following:

• The directory structure: app/, lib/ct/, lib/mappers/, hooks/, components/, and context/
• The BFF data-fetching pattern and its no-fetch-in-the-client rule
• The session shape, and the type boundary with its mapper layer
• One BCP-47 locale format everywhere.
• Locale, currency, and country treated as a single atomic change, with the Cart reset whenever the currency changes (a commercetools Cart's currency is immutable)
• On B2B: every user-facing write through the as-associate chain, and every business-unit-scoped cache keyed by business unit.

And it does not interfere with the rest, such as:

• Your visual design system beyond the Tailwind baseline
• State management beyond Stale-While-Revalidate (SWR)
• Your testing framework and CI pipeline
• Any deployment target past the bundled Vercel and Netlify configs
• All of your business logic, merchandising rules, and content

How the pieces fit together

The agent reasons with the skills as standing context and reaches for the Knowledge MCP whenever it needs a current fact. It writes ordinary Next.js code that talks to your Project through the SDK. The agent is nowhere in the runtime path of your live storefront. It produces the code, but the code runs on its own.

Adapt to your stack

To adapt the plugin to your tech stack, you have three options:

• Use it as-is: the fastest path. You get a coherent reference implementation with the agent keeping it consistent for you, and it's the right call when you're starting fresh or building a proof of concept.
• Fork the skills: when you have a handful of deliberate divergences, say a different session strategy or a different styling system, and you want the agent to apply them consistently, fork the repo, edit the relevant SKILL.md and references, and point your agent at your fork.
• Use it as a reference only: read the SKILL.md files for the patterns but don't install them. You get the architectural thinking without the agent auto-applying it, as long as you accept that it then won't reach for these patterns on its own.