agentleFS
sadrmaneshsadrmanesh/commerce-agent-skills/skills/headless-nextjs-storefront/SKILL.md

headless-nextjs-storefront

Skill1 starsChanged 18 days agoMITView on GitHub

Build a Next.js storefront that loads catalog data on the server, keeps admin secrets off the client, and revalidates price and stock. Use when adding product, cart, or checkout UI in a Next.js App Router storefront for WooCommerce or another headless commerce API.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this skill for a Next.js storefront that talks to a commerce API.

    line 12
  2. Distinctive:

    Keep admin credentials and WooCommerce consumer secrets in server environment variables.

    line 19
  3. Very specific:

    Use the public storefront API for the cart.

    line 20
  4. Very specific:

    Call revalidateTag('product:<id>') or revalidatePath from the server path that handles the catalog webhook.

    line 34
  5. Distinctive:

    Use the Storefront API for product and cart reads.

    line 44
  6. Distinctive:

    Do not send the Admin API token to the browser.

    line 45

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Headless Next.js storefront

Use this skill for a Next.js storefront that talks to a commerce API. WooCommerce HTTP details are in the REST API skill. Shopify admin apps are a different skill. Checkout field behavior is the checkout skill.

This skill assumes the App Router (app/). Do not pin a Next.js major version you have not installed. Use the cache and route APIs that version documents.

Procedure

  1. Render product and category pages from the server. The HTML should contain the price and availability a shopper and a crawler see.
  2. Keep admin credentials and WooCommerce consumer secrets in server environment variables. Never import them into a client component.
  3. Use the public storefront API for the cart. For WooCommerce that is the Store API (/wp-json/wc/store/v1/), with its cart token and nonce. It is not wc/v3.
  4. Cache catalog reads. Invalidate that cache when price or stock changes. Do not cache a cart response as if it were a public product.
  5. Re-check the charged total on the server when checkout starts. The figure in React state is not the amount to capture.

Cache and cart boundaries are in the cache notes. Worked examples and checks are in evals/tasks.json.

Data split

DataWhere it is readCache
Product title, price, stock, imagesServer component or a route handlerPublic cache with a tag such as product:<id>
Cart and checkout sessionServer route that forwards the shopper's cart tokenDo not use the public product cache
Admin writesServer only, with the admin credentialDo not expose the route to the browser without your own auth

Call revalidateTag('product:<id>') or revalidatePath from the server path that handles the catalog webhook. A client component cannot import next/cache revalidation and run it in the browser.

WooCommerce storefront

  • Product pages may use a read-only integration on the server. Prefer a key that cannot write, or a public product endpoint your store already exposes.
  • Cart requests send the Cart-Token the Store API returned. Store that token in an HTTP-only cookie set by your server route, not in localStorage, if the token would let someone else modify the cart.
  • The browser calls your Next.js route. Your route calls WooCommerce. Do not point the browser at wc/v3 with a consumer secret.

Shopify storefront

  • Use the Storefront API for product and cart reads. The Storefront access token is still a secret if it can create checkouts. Follow the token type Shopify documents for that API.
  • Do not send the Admin API token to the browser.

Rendering

  • Format money with the storefront locale on the server so the HTML and the JSON-LD match. Persian digits belong in visible text, not in the amount you post to checkout. See the RTL skill.
  • Variant selection updates the visible price to that variant before add-to-cart.
  • Out-of-stock variants stay disabled even if a cached page is briefly stale. The add-to-cart route checks stock again.

Gotchas

  • cache: 'force-cache' on a cart GET will show one shopper another shopper's cart if the URL does not vary. Do not cache cart responses on a shared key.
  • A webhook that updates stock must revalidate the product tag. Restarting the Next.js process is not an invalidation strategy.
  • Client-side fetch to a route that embeds the admin secret in the response will leak it into the browser. Return only the fields the UI needs.
  • Draft-mode or preview cookies should not be cached as public product HTML.

Verification

  • The built HTML for a product contains the price without requiring client JavaScript.
  • Searching the client bundle finds no consumer secret and no Admin API token.
  • Updating a price and delivering the catalog webhook changes the next product response without a redeploy.
  • Two browsers do not share a cart token.

Evaluation

Worked examples and the checks they must satisfy are in evals/tasks.json.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.