cloudcart-nitrogen
Skill2 starsChanged 3 months agoMITView on GitHub
Build or change a CloudCart headless storefront made with Nitrogen — a React Router app whose package.json depends on @cloudcart/nitrogen. Use for any change to such a storefront: a new page or route, a component or section, the design, a GraphQL query or mutation, a form, caching, the cart, the customer account, analytics, SEO, speed, or a review of such a change. Five stages in order: the store's niche and a mobile-first design; the build on Nitrogen's building blocks with GraphQL that fetches only what the page renders; SEO and security; the analytics and the merchant's pixels; a whole-site review — caching, queries, SEO, a mobile speed score of 90 or more. Covers Nitrogen 2.4. In Bulgarian: витрина с Nitrogen, headless магазин, нова страница, нов компонент, дизайн, мобилна версия, GraphQL заявка, кеширане, бързодействие, количка, профил на клиента. NOT for the Admin API or a store's own data (use cloudcart-product-management), and NOT for how the platform itself behaves (use cloudcart-platform-expert).
- Reads credentials
In this repository5 other files it gives its agents.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Read version in node_modules/@cloudcart/nitrogen/package.json (install the dependencies first if node_modules is missing).
- Distinctive: line 36
Every task starts here, before the first line, however small:
- Very specific: line 78
The store's niche: Ask which kind of store it is (fashion, electronics, food, …), or read it from the catalogue.
- Very specific: line 125
The CSP nonce: Every inline script carries the request's nonce: nitrogen-react's <Script>, or useNonce().
- Very specific: line 137
Before a release, and for every page a change touches, however small — open references/quality.md and go through its checklist:
- Very specific: line 143
SEO: every indexable page passes references/seo.md's checklist.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Building a Nitrogen storefront
This skill covers Nitrogen 2.4: @cloudcart/nitrogen and @cloudcart/nitrogen-react 2.4.2 and later 2.4.x.
Nitrogen is CloudCart's framework for headless storefronts. A storefront is a React Router 7 app, created from CloudCart's starter, that runs on Cloudflare Workers and reads the store through the CloudCart Storefront GraphQL API. The checkout is the platform's own: the storefront hands the cart over through cart.checkoutUrl.
Work in five stages, in this order: the store and its design, the build, SEO and security, analytics and pixels, and a review of the whole site. A new storefront goes through all five. A smaller change goes through the stages it touches, in the same order, and always ends with stage 5 for the pages it changed. The details are in references/; open the one a stage points to when you reach it.
0. Which Nitrogen
Read version in node_modules/@cloudcart/nitrogen/package.json (install the dependencies first if node_modules is missing).
- 2.4.2 and later 2.4.x: this skill applies as written.
- 2.4.0 and 2.4.1: all of it but what 2.4.2 added: the listing's arguments in
references/graphql.md, "A listing's filters and counts" (filters(ids:),filterCapabilities(ids:),ProductFilter.anyOf,marketingFilters(groups:),collections(productFilters:);npm run codegenrefuses them), Aura Search'suseSearchReportandsearchHighlights(references/tracking.md),reloadOnNewBuild()and a shared page kept per build (references/speed.md). On 2.4.0 and 2.4.1 a query that names no cache strategy is fresh for 1 second, not 5 minutes; 2.4.0 also lacksmarketingFilterson a search's results, which 2.4.1 added. Moving to^2.4.2removes no export: propose it to the user, and until then skip what this skill says of those parts. - 2.3.1 and later 2.3.x: as 2.4.0, and without the merchant's label, banner and campaign filters (
productLabel,productBanner,productDiscountandmarketingFilters), which came with 2.4.0. - 2.3.0: as 2.3.1, and without CloudCart Pay's Apple Pay and Google Pay buttons (
<CloudCartPayExpress>,handleCloudCartPayExpressRequest,getCloudCartPayExpressSettingsinreferences/storefront-foundations.md), which came with 2.3.1. Move to^2.3.1before adding them; the buttons are the project's code too — the starter'sapp/components/WalletButtons.tsxandapp/routes/api.cloudcart-pay-express.tsx. - 2.2.x: as 2.3.0, and without what 2.3 added: the kept pages (
KeptLink,keptPageLoader,useKeptPages,keptSectionLoaderinreferences/speed.md), a variant opened by its id in the address (loadAddressVariantOptions,references/design.md), and CloudCart Analytics' events and the real visitors' speed sent from the browser (references/tracking.md); on 2.2 a step back loads the page again and the API sends the events itself. Moving to^2.3.0removes no export, but the kept pages are the project's code too — each shared route'sclientLoader, the root'suseKeptPagesand the links — and over HTTPS the session cookie becomes__Host-session, so a signed-in customer signs in once more: propose it to the user, and until then skip what this skill says of the kept pages. - 2.1.x: as 2.2.x, and without the metafields and metaobjects (
references/metafields.md): 2.1 ships a schema without them, sonpm run codegenrefuses their fields, and it has no<MetafieldRichText>and fewer ofparseMetafield's types. - 2.0.x: as 2.1.x, and without the page cache (
createPageCache, and the visitor's own data from/visitor), which came with 2.1: on 2.0 every page is rendered for each request. The page cache is the project's code too — the starter'sserver.ts,app/lib/page-cache.ts,app/routes/visitor.tsx,app/lib/visitor.server.tsand the root's visitor parts: until it is there, skip what this skill says of the page cache: no route getshandle = SHARED_PAGE, and stage 5'sMISS-then-HITcheck is not made. - Another major or minor version: tell the user that this skill may lag that release. The installed packages'
EXPORTS.mdandREADME.mdalways describe the installed version: where they differ from this skill, follow them.
Before you write code
Every task starts here, before the first line, however small:
- The API, from the storefront MCP. Call
learn_cloudcart_storefrontonce in a session; it answers with theconversationIdthe other tools take, and names the operation for what you want to do when you do not know its name. Then look up each type, query or mutation the task touches by name withintrospect_graphql_schema(Product,Cart,predictiveSearch). What they already give — a price asformatted, a discount, a count, a field you were about to compute — decides what the page asks for, and what it must never compute itself. The MCP is@cloudcart/storefront-mcp, which the CloudCart plugin registers; if your host lists its tools as deferred, load them; if it is not installed, say so in your report. - The starter's way. Open the starter's nearest page and components (the table below), and
references/storefront-foundations.md: what the starter already gives every storefront — the frame around the pages, analytics and its events, cookie consent and the data requests, scripts from outside, the pop-ups and forms. - The merchant's own data. When the page shows something the platform has no field for — a size chart, specifications, a designer, a section the merchant edits — open
references/metafields.md: the wiki's use case for it, what the merchant sets up, and how to read and show it. - A reuse map. Before a new page or section, write it down and show it to the user: what exists and is used as it is (a component, a fragment, a helper, a Nitrogen export), what is extended (a prop or a variant of a component that exists), and what is missing and becomes a building block (stage 2). For a small fix, it goes into your report.
- The page's elements. List every element the page shows — from the design, or from the starter's page — and every state it can be in: loading, empty, failed, signed in or out, sold out, one picture or many. Stage 5 checks each of them.
- The "before". Measure the page as it is: its calls and its times (
references/speed.md). A new page has no "before": measure the nearest page of its kind, and the new one after.
Build on the starter, never over it. The storefront's look is the project's own code — the merchant's theme in the admin plays no part in it (stage 5). A change goes through the design tokens (app/styles/app.css) and the props of the components that exist. Never a second component beside one that does the same job (another product card, another price), never CSS that overrides a component's own, never a copy of a starter file to change it there. When a component lacks something, extend it where it is, so every page that uses it gets it.
The starter is the reference
The project was created from CloudCart's starter (the public template cloudcart/nitro-starter), so its files are in the project; where the project has changed one, the template on GitHub (github.com/cloudcart/nitro-starter) has the original. The starter is how things are done in a Nitrogen storefront: its speed, caching, SEO, security, analytics, forms and design are the standard a change meets. Before you write a page, a section or a form, open the starter's nearest one and do it the same way; where this skill and the starter's code agree, the code is the worked example.
| What | Where the starter shows it |
| Critical and deferred data | app/routes/_index.tsx (loadDeferredData), app/routes/product.$handle.tsx and its parent app/routes/product.tsx (the reviews, which a variant change does not reload) |
| Pictures: the first eager, the rest lazy | app/components/ProductGallery.tsx, app/components/Hero.tsx |
| Cache strategies | app/root.tsx and app/lib/product-page.ts (CacheSettings() for the shop and the merchant's settings), a visitor's own answer kept from every cache by Nitrogen's request handler (context.personal.mark() for what it cannot see) |
| The page cache and the visitor's own data | server.ts (createPageCache), app/lib/page-cache.ts (SHARED_PAGE), app/routes/visitor.tsx, app/lib/visitor.server.ts |
| A page that opens at once | app/components/PageTransition.tsx, app/components/PendingPage.tsx, app/lib/opening.ts |
| What is around every page | AppShell in app/root.tsx, app/components/PageLayout.tsx (references/storefront-foundations.md) |
| SEO | app/lib/meta.ts, each route's meta, app/routes/[robots.txt].tsx |
| Security | server.ts (Nitrogen's request handler, storeDomain), app/entry.server.tsx (the CSP), Nitrogen's localRedirectPath (a redirect target from the request), a visitor's own answer private, no-store (Nitrogen's request handler; context.personal.mark()) |
| Analytics | app/root.tsx (<Analytics.Provider>), app/lib/analytics.ts (listedProducts), each page's view |
| Listings and cards | app/routes/category.$handle.tsx, app/components/ProductListing.tsx, app/components/ProductItem.tsx |
| Forms | app/components/ProductRequestForms.tsx, app/components/ui/Field.tsx (16 px text on a phone), the routes under app/routes/account* |
| Design | app/styles/app.css (the tokens), app/components/ui/ |
The starter's pages are held to the same targets as yours: the request budget (references/graphql.md) and stage 5's review. When the project's copy has drifted from the starter in a way this skill says is wrong, follow the skill and tell the user.
What reaches the live store
- A push deploys. The platform's workflow in the repository (
.github/workflows/nova-deploy.yml) deploys a push to the default branch to the merchant's live storefront, and an older copy of it deploys a pull request too: read it. Push, open a pull request or runcloudcart nitrogen deployonly when the user says so.deployneeds the storefront's deployment token inCLOUDCART_NOVA_TOKEN(.env), made in the admin on the storefront's Deployments tab, under Deployment tokens;cloudcart llms-contextdescribes every CLI command. - The dev server and GraphiQL work on the live store. A fast order, a payment with CloudCart Pay's Apple Pay or Google Pay buttons, a contact or inquiry form, a review, a newsletter sign-up, a subscription or a back-in-stock request sent from them is real: an order, a charge, a mail, a subscriber. Send one only with the user's word, and tell them what it made.
- Test visits can reach the merchant's ad accounts: stages 4 and 5 say when to ask.
Stage 1. The store and its design — references/design.md, references/store-kinds.md
Decide what the storefront looks like and holds before writing code: the pages, their sections and the data each one shows. That decides the components and the queries of stage 2.
- The store's niche. Ask which kind of store it is (fashion, electronics, food, …), or read it from the catalogue. The kind decides the structure of the search, the listings, the product cards and the product page:
references/store-kinds.md. - Mobile first. Design every page for a phone first (360–390 px wide), then add what a wider screen allows. A phone's small screen and slower network are the hardest case, and stage 5's speed target is measured on one.
- The best practice of UX for a store: the search, the listings, the cards, the product page, the cart and the feedback on every action, in
references/design.md. - What the merchant edits without code. Sections, banners, a size chart, a designer's profile: model them with metaobjects and metafields, from the wiki's use cases (
references/metafields.md), and agree the model with the merchant before the pages. - One accent colour, and one or two complementary ones. The accent marks what the visitor acts on (the main button, links, focus); a complementary colour marks products (a discount); everything else is neutral. They are design tokens: in the starter,
--color-accentand--color-highlightinapp/styles/app.css. Set them from the merchant's brand, with enough contrast.
Stage 2. The build — references/graphql.md, references/speed.md, references/building-block.md, references/metafields.md
Look it up, then use it
- Read the export maps of the installed version.
node_modules/@cloudcart/nitrogen/EXPORTS.mdis the core: the Storefront API client and its cache strategies, the cart, the customer account, analytics, SEO, the CSP, translations, pagination, routing and the Vite plugin.node_modules/@cloudcart/nitrogen-react/EXPORTS.mdhas the React components and hooks:Money,Image,ProductPrice,AddToCartButton,RichText,PaginatedResourceSection, the privacy banner, the subscribe forms and more. Each export has its kind and the first sentence of its documentation; the full documentation is on the export itself, and each package'sREADME.mdexplains the wiring. - Look at what the project already has, and at the starter's nearest page (above). Then search
app/routes/(one file per page),app/components/(small UI pieces inapp/components/ui/),app/lib/(helpers, fragments, the platform's page addresses inurls.ts, themetahelpers inmeta.ts),app/building-blocks/once the project has one (below, "A missing building block") andapp/locales/(one JSON file per language). - Use what exists. Never re-create a piece that Nitrogen or the project already has: a price, an image, a cart form, pagination, SEO tags, a consent banner, a translation helper. If a piece almost fits, use its props or wrap it. If a Nitrogen piece is wrong, report it to the user, and do not fork it.
- Take data from the API; never derive it. Prices and totals come as
formatted, the discount fromProduct.discount, the cart's totals fromCart.totals. If the API gives a wrong value, report it, and do not compute around it. One exception: a quantity tier card's figures for pieces of several variants, which the API cannot give one by one, are added up from the variants' per-piece prices (ProductVariant.quantityDiscounts) by the cart's rule and written with the store's format (moneyWithFormatwithShop.currencyFormat), as the starter'sapp/lib/quantity-tiers.tsdoes. Pages keep the platform's addresses (/product/{handle},/category/{handle}, …), and the checkout stays the platform's. - The merchant's content (pages, articles, descriptions) is HTML from the store: render it with
<RichText>, which names an untitled embedded frame (<iframe>) from its source, so a screen reader can announce it. When a page embeds frames, tell the merchant to give each one atitle.
GraphQL that fetches only what the page renders
- GraphQL, not REST. One document for each moment of the page asks for the whole shape it renders. A page splits its calls only by cache lifetime, by critical and deferred data, when one call needs another's answer, or where a Nitrogen helper runs its own; never one call per resource. Values go in variables, related data is nested, the same field twice is an alias, an optional part is
@include, a mutation's payload carries the new state, and the API filters, sorts and pages. A list inside a list asks each item's first page, for a few items fixed in the document. The REST habits, and how each shows in the code:references/graphql.md. - Colocated. A query lives in the route module that runs it; one that several routes run lives under
app/lib/. A fragment that one route uses lives in that route; one that several share lives beside the component that renders it (COLLECTION_CARD_FRAGMENTinCollectionGrid.tsx) or, when no one component owns it — the product card's, the user errors' — inapp/lib/fragments.ts; the query spreads it. Select only the fields the page renders: a field "for later" costs every visit. - One server request per page. Data loads in the route's
loader. Await only what the first screen needs; start the rest first and render it in<Suspense>with<Await>. A section below the first screen takes its fields from the page's existing deferred query; a list of products the visitor may never scroll to is asked for only as they near it (references/graphql.md). - Within the page's request budget. Independent calls run together, never more than 6 at a time (the Workers limit). No N+1: a list's items come in the list's own query.
- No client-side fetching of server data. The browser gets data from loaders, and changes it through the app's actions:
<CartForm>, oruseFetcherposting to a route. It reaches sf only through the storefront's own/api/sfproxy, and only for what Nitrogen does there itself: a customization file's upload (uploadCartCustomizationFile), the cookie consent and the analytics events. - Pagination with
getPaginationVariables(request, {pageBy})in the loader, andPaginatedResourceSection(or<Pagination>) in the page; both directions work. - The right cache strategy for each query:
CacheLong()only for menus and static lists,CacheSettings()(a minute) for settings the merchant edits, the default (5 minutes) for the catalogue and content, orCacheShort()(a second) where a price or stock level must show within seconds,CacheNone()for what visitors must see at once after they change it. A query that passes the buyer is cached for that buyer alone. - The page cache for a page that is the same for every visitor who is not signed in:
handle = SHARED_PAGE, with nothing of the visitor's in its loader — their own parts come from/visitorin the browser (references/speed.md). - A page that opens at once: a click shows the page being opened from what the link already showed, and its data fills it in place; a next page starts loading before the visitor reaches it (
references/speed.md). - The signed-in buyer goes to the API as the
buyervariable with@inContext(buyer: $buyer), fromcustomerAccount.getBuyer(). The customer's own data is read withcustomerAccount.queryand changed withcustomerAccount.mutate, which never cache. - The page's address. A loader or action reads it from its
urlargument, never fromnew URL(request.url): with React Router's v8 flags,requestis the data request (/product/x.data?_routes=…). Nitrogen's helpers that take arequestcorrect this themselves. - Validate every query and mutation with the storefront MCP's
validate_graphql_codeblocks(you calledlearn_cloudcart_storefrontbefore writing code; should its guide ever differ from this skill, this skill wins), thennpm run codegen. Codegen does not replace it: it checks the schema only, and the MCP also catches documents that pass the schema and still fail. The storefront MCP is@cloudcart/storefront-mcp, which the CloudCart plugin registers; the Dev MCP (@cloudcart/dev-mcp) has a tool of the same name that checks the Admin API only, never a storefront document. If your host lists the MCP's tools as deferred, load them; if the MCP is not installed, say so in your report. The API refuses a query deeper than 10 levels or with a complexity over 1000. - Mutations answer with
userErrors(customerUserErrorsfor the customer's own): show them next to their field; never throw them.
A missing building block
Build it the way Nitrogen builds its own, so it can move into Nitrogen as it is: in app/building-blocks/, one file per block with its test beside it; unstyled, with cc-<block>-<part> class hooks and classNames; its data through props, typed from its fragment; links through props; documented; tested with vitest; named to the user as a candidate for Nitrogen. The details are in references/building-block.md.
Stage 3. SEO and security — references/seo.md
SEO, for every indexable page:
- Rendered on the server;
metawith the starter'sseoMeta(title, description, the canonical on the store's domain, image),privateMetaon a private or form page. - A listing's pages each their own canonical (
listingUrl); structured data (Product, Organization, Article, BreadcrumbList) with Nitrogen's helpers; a description on every page; alt text on content images; a 404 for a missing record.
Security:
- Tokens stay on the server.
PUBLIC_STOREFRONT_API_TOKENmay reach the browser.PRIVATE_STOREFRONT_API_TOKENandSESSION_SECRETare used only in server code, never in a component, a client module or anything rendered. Values live in.env, which is never committed, and in the storefront's environment in the CloudCart admin (cloudcart nitrogen env pull). Never print them. - The customer's access token stays in the signed session cookie, and Nitrogen's
customerAccountsends it. Never in a URL, browser storage, client code or anAuthorizationheader. - The CSP nonce. Every inline script carries the request's nonce: nitrogen-react's
<Script>, oruseNonce(). A third-party source is added to the policy inapp/entry.server.tsx. Never loosen the CSP to make a script run. - Forms are validated by the API: a route action submits to the mutation and shows its
userErrors. Checks in the browser are a convenience only. - A customer's data goes only to that customer: read with
customerAccount.query. Nitrogen's request handler answers a visitor's own pageprivate, no-storeby itself — a signed-in customer's, one that reads or changes the cart, a form's, one that sets a cookie — whatever a route'sheaderssaid; a loader that reads a record by a reference the visitor holds (a return by its reference) says so withcontext.personal.mark(reason). Such a page is never in the page cache. A page is shared only through the page cache, which renders it without the visitor's cookies and leaves their own parts to the browser (references/speed.md); never set a sharedCache-Controlyourself.
Stage 4. Analytics and the merchant's pixels — references/tracking.md
- The wiring stays as the starter has it:
<Analytics.Provider>in the root, with the shop, the cart, the consent and the merchant's pixels from the admin. Never add a vendor's script by hand. - Each page renders the view for its kind (
<Analytics.ProductView>,<Analytics.CollectionView>, …), once; a page of another kind renders none. - Check that they fire: a dev server sends nothing to CloudCart Analytics; in the browser's console, one
[nitrogen] CloudCart Analytics: PAGE_VIEW (…)per page view, plus the page's own view (VIEW_CONTENTon a product,SEARCHon a search; the cart page's view is itsPAGE_VIEW (CART), and opening the cart drawer showsVIEW_CART); an add to cart showsADD_TO_CARTonce. In the network panel, before the visitor's choice, no request to a vendor of a group that waits for consent; after it, the vendors receive the page's events — real events in the merchant's ad accounts: ask the user first (references/tracking.md). Report what you saw, or that you could not open a browser.
Stage 5. The review of the whole site — references/verification.md, references/quality.md, references/speed.md
Before a release, and for every page a change touches, however small — open references/quality.md and go through its checklist:
- Caching: on a second load the profiler (
/__nitrogen/subrequests) shows the shared data asHITorSTALE; each query has the strategy its data needs; on the deployed storefront a shared page answersMISS, thenHIT; private pages are never cached. - The queries: each page's calls against its budget, no N+1, none of the REST habits in
references/graphql.md, no field the page does not render, and where a call or a field can go. Report the numbers before and after. - Times: each changed page's data on a click, cached and not, and the time to the waiting page and to the page's content, with no layout shift after the click — before and after (
references/speed.md). - Every element in every state: the list you made before writing code, each element checked on a phone and a desktop.
- SEO: every indexable page passes
references/seo.md's checklist. - Speed: a Lighthouse performance score of at least 90 on a phone (its default mobile profile) for the home, a category and a product page — Lighthouse on the production build, or PageSpeed Insights on the live site. A test visit to a store that reports server-side reaches the merchant's ad accounts: ask the user first (
references/verification.md). Report the scores and what holds them back. npm run checkpasses (codegen, typecheck, lint, build, and the tests once there are any), and the whole checklist inreferences/quality.mdis gone through.- Report what you measured, with the numbers. "It should be fine" is not a measurement.
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.

