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.
In this repository28 other files it gives its agents.
- b2b-pricingSkill
- catalog-import-and-migrationSkill
- checkout-ux-and-conversionSkill
- conversion-event-trackingSkill
- ecommerce-seo-structured-dataSkill
- fraud-and-risk-basicsSkill
- google-merchant-product-feedsSkill
- inventory-and-multi-warehouseSkill
- iranian-payment-gatewaysSkill
- marketplace-search-and-rankingSkill
- mcp-store-toolingSkill
- multi-vendor-payoutsSkill
- order-and-webhook-reliabilitySkill
- payment-gateway-integrationSkill
- product-catalog-modelingSkill
- product-description-guardrailsSkill
- returns-and-refundsSkill
- rtl-and-persian-localizationSkill
- shopify-app-developmentSkill
- storefront-accessibilitySkill
- storefront-performanceSkill
- stripe-paymentsSkill
- subscription-billingSkill
- tax-and-shippingSkill
- vector-product-searchSkill
- woocommerce-plugin-developmentSkill
- woocommerce-rest-apiSkill
- wordpress-plugin-securitySkill
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
- Very specific: line 12
Use this skill for a Next.js storefront that talks to a commerce API.
- Distinctive: line 19
Keep admin credentials and WooCommerce consumer secrets in server environment variables.
- Very specific: line 20
Use the public storefront API for the cart.
- Very specific: line 34
Call revalidateTag('product:<id>') or revalidatePath from the server path that handles the catalog webhook.
- Distinctive: line 44
Use the Storefront API for product and cart reads.
- Distinctive: line 45
Do not send the Admin API token to the browser.
≈ “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.
Files
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
- Render product and category pages from the server. The HTML should contain the price and availability a shopper and a crawler see.
- Keep admin credentials and WooCommerce consumer secrets in server environment variables. Never import them into a client component.
- 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 notwc/v3. - Cache catalog reads. Invalidate that cache when price or stock changes. Do not cache a cart response as if it were a public product.
- 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
| Data | Where it is read | Cache |
| Product title, price, stock, images | Server component or a route handler | Public cache with a tag such as product:<id> |
| Cart and checkout session | Server route that forwards the shopper's cart token | Do not use the public product cache |
| Admin writes | Server only, with the admin credential | Do 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-Tokenthe Store API returned. Store that token in an HTTP-only cookie set by your server route, not inlocalStorage, 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/v3with 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
fetchto 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.
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
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.

