Skip to content

Commit 1894a1b

Browse files
alexphelpsalexphelps
committed
add graphql overview
1 parent d1a5bee commit 1894a1b

7 files changed

Lines changed: 229 additions & 31 deletions

File tree

‎.claude/rules/graphql-docs.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Storefront GraphQL API Docs Generator
2+
3+
## Overview
4+
5+
The Storefront GraphQL API reference docs are auto-generated from the live schema at build time. The pipeline introspects `https://aptest.29next.store/api/graphql/`, generates MDX scaffold pages via `@graphql-markdown/cli`, then post-processes them into a custom two-column layout with inline type expansion and example code panels.
6+
7+
The GraphQL endpoint is available on every store at `https://{subdomain}.29next.store/api/graphql/` — the subdomain is the only thing that changes per store.
8+
9+
## Architecture
10+
11+
### Generation pipeline (`npm run generate-graphql-docs`)
12+
13+
Runs `scripts/generate-graphql-docs.mjs` which executes three phases:
14+
15+
1. **`gqlmd graphql-to-doc`** — Uses `@graphql-markdown/cli` with config from `graphql.config.mjs` to introspect the schema and generate raw MDX pages into `content/docs/storefront/graphql/`.
16+
17+
2. **Flatten & clean** — Moves `operations/queries/` and `operations/mutations/` up to top level, deletes `types/`, `directives/`, and `operations/` directories. Writes a clean `index.md` landing page and `meta.json`.
18+
19+
3. **Introspect & rewrite operations** — Fetches the schema again via introspection query, then for each query/mutation:
20+
- Builds structured field data (args + return fields) with **full recursive type expansion** and cycle detection via `seen` set
21+
- Generates example operation signature (GraphQL), variables (JSON), and response (JSON)
22+
- Rewrites each `.mdx` file with the `<GraphQLOperation>` component, passing all data as props
23+
- Sets `full: true` in frontmatter for full-width layout
24+
25+
### Key files
26+
27+
| File | Purpose |
28+
|------|---------|
29+
| `scripts/generate-graphql-docs.mjs` | Main generation + post-processing script |
30+
| `graphql.config.mjs` | `@graphql-markdown/cli` config — schema URL, output path, MDX formatter |
31+
| `lib/graphql-mdx-formatter.cjs` | Maps graphql-markdown admonitions/badges to fumadocs `<Callout>` components |
32+
| `components/graphql-operation.tsx` | Client component — two-column layout with inline accordions + code panels |
33+
| `components/mdx.tsx` | Registers `GraphQLOperation` in the MDX component map |
34+
| `content/docs/storefront/graphql/` | Generated output directory |
35+
| `content/docs/storefront/meta.json` | Parent sidebar config (includes `"graphql"` in pages array) |
36+
37+
### Output structure
38+
39+
```
40+
content/docs/storefront/graphql/
41+
├── index.md ← Landing page
42+
├── meta.json ← Sidebar: { title: "Storefront GraphQL API", pages: ["queries", "mutations"] }
43+
├── queries/
44+
│ ├── cart.mdx
45+
│ ├── me.mdx
46+
│ ├── product.mdx
47+
│ └── products.mdx
48+
└── mutations/
49+
├── add-cart-lines.mdx
50+
├── create-cart.mdx
51+
└── ... (13 total)
52+
```
53+
54+
### Operation page layout (`GraphQLOperation` component)
55+
56+
Two-column layout using `@container` queries (breaks out of prose with `not-prose max-w-none`):
57+
58+
- **Left column**: Description, Arguments (with recursive inline accordions), Return type (with recursive inline accordions)
59+
- **Right column** (sticky): Query/Mutation Reference (`DynamicCodeBlock` graphql), Variables (`DynamicCodeBlock` json), JSON Response (`DynamicCodeBlock` json)
60+
61+
All types expand inline via accordion — no separate type pages. Cycle detection prevents infinite recursion on self-referencing types.
62+
63+
### Build integration
64+
65+
Wired into `package.json` scripts:
66+
```
67+
"dev": "node scripts/generate-api-docs.mjs && npm run generate-graphql-docs && next dev --turbopack"
68+
"build": "node scripts/generate-api-docs.mjs && npm run generate-graphql-docs && next build"
69+
"generate-graphql-docs": "node scripts/generate-graphql-docs.mjs"
70+
```
71+
72+
### Dependencies
73+
74+
- `@graphql-markdown/cli` — Generates initial MDX scaffold from schema introspection
75+
- `@graphql-tools/url-loader` — Fetches schema from live HTTP endpoint
76+
77+
## Important conventions
78+
79+
- The schema source of truth is `https://aptest.29next.store/api/graphql/` (the `aptest` store)
80+
- Generated files in `content/docs/storefront/graphql/` are committed to git (same convention as REST API docs)
81+
- The `meta.json` title is "Storefront GraphQL API" (set by the user, do not override)
82+
- Operation filenames use kebab-case derived from the camelCase operation name (e.g., `createCart` → `create-cart.mdx`)
83+
- The `full: true` frontmatter flag triggers full-width layout (hides TOC, sets max-width 1400px)
84+
- Link styling matches the docs prose defaults: `text-fd-foreground underline decoration-fd-primary decoration-[1.5px] underline-offset-[3.5px]`
85+
- `source.config.ts` includes `graphql` in the syntax highlighting languages list

‎content/docs/storefront/api.mdx‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎content/docs/storefront/graphql/index.md‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎content/docs/storefront/graphql/index.mdx‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Storefront GraphQL API
3+
---
4+
5+
import { Callout } from 'fumadocs-ui/components/callout';
6+
7+
Build custom sidecarts, upsell flows, and dynamic storefront experiences with the Storefront GraphQL API. Query products, manage carts, apply vouchers, and handle user accounts — all from your theme's JavaScript or any client-side application.
8+
9+
## API Endpoint
10+
11+
Every store exposes a GraphQL endpoint at:
12+
13+
```
14+
POST https://{store}.29next.store/api/graphql/
15+
```
16+
17+
All requests must be `POST` with `Content-Type: application/json`. Replace `{store}` with your store's subdomain.
18+
19+
## Authentication
20+
21+
The Storefront API is available within the context of your storefront on a storefront domain. Requests made from your theme's JavaScript automatically inherit the user's session — no API keys or tokens needed.
22+
23+
<Callout type="info">
24+
External access to the Storefront API (outside of the storefront context) will be available in future iterations.
25+
</Callout>
26+
27+
28+
## Interactive Explorer (GraphiQL)
29+
30+
Every store includes a built-in **GraphiQL IDE** — an in-browser tool for writing, validating, and testing GraphQL queries directly against your store's schema. Navigate to `/api/graphql/` on your store to open it.
31+
32+
GraphiQL lets you:
33+
34+
- **Explore the schema** — browse all available queries, mutations, types, and their fields using the documentation sidebar
35+
- **Build queries visually** — use the explorer panel to construct queries by selecting fields, without writing GraphQL by hand
36+
- **Test in real-time** — run queries and mutations against your store and see the JSON response instantly
37+
- **Validate syntax** — get inline error highlighting and autocomplete as you type
38+
39+
```
40+
https://{store}.29next.store/api/graphql/
41+
```
42+
43+
This is the fastest way to learn what the API offers and prototype queries before adding them to your theme code.
44+
45+
46+
## API Reference
47+
48+
### Queries
49+
50+
- [`cart`](/docs/storefront/graphql/queries/cart) — Retrieve a cart by ID
51+
- [`me`](/docs/storefront/graphql/queries/me) — Get the current authenticated user
52+
- [`product`](/docs/storefront/graphql/queries/product) — Fetch a single product
53+
- [`products`](/docs/storefront/graphql/queries/products) — Query the product catalog
54+
55+
### Mutations
56+
57+
- [`createCart`](/docs/storefront/graphql/mutations/create-cart) — Create a new cart
58+
- [`addCartLines`](/docs/storefront/graphql/mutations/add-cart-lines) — Add line items to a cart
59+
- [`updateCartLines`](/docs/storefront/graphql/mutations/update-cart-lines) — Update quantities on existing cart lines
60+
- [`removeCartLines`](/docs/storefront/graphql/mutations/remove-cart-lines) — Remove line items from a cart
61+
- [`emptyCart`](/docs/storefront/graphql/mutations/empty-cart) — Remove all items from a cart
62+
- [`addVoucher`](/docs/storefront/graphql/mutations/add-voucher) — Apply a voucher code to a cart
63+
- [`removeVoucher`](/docs/storefront/graphql/mutations/remove-voucher) — Remove a voucher from a cart
64+
- [`updateCartAttribution`](/docs/storefront/graphql/mutations/update-cart-attribution) — Set UTM and affiliate attribution on a cart
65+
- [`updateCartMetadata`](/docs/storefront/graphql/mutations/update-cart-metadata) — Update custom metadata on a cart
66+
- [`register`](/docs/storefront/graphql/mutations/register) — Register a new customer account
67+
- [`tokenAuth`](/docs/storefront/graphql/mutations/token-auth) — Authenticate and obtain a token
68+
- [`verifyToken`](/docs/storefront/graphql/mutations/verify-token) — Verify an authentication token
69+
- [`updateAccount`](/docs/storefront/graphql/mutations/update-account) — Update the current user's account details
70+
71+
72+
## Quick start
73+
74+
Fetch the current cart to build a custom sidecart UI:
75+
76+
```bash title="Example: Query the cart"
77+
curl -X POST https://yourstore.29next.store/api/graphql/ \
78+
-H "Content-Type: application/json" \
79+
-d '{
80+
"query": "query Cart($id: ID!) { cart(id: $id) { id numItems totalInclTax currency lines { edges { node { id quantity product { title } linePriceInclTax } } } } }",
81+
"variables": { "id": "<cart-id>" }
82+
}'
83+
```
84+
85+
```json title="Response"
86+
{
87+
"data": {
88+
"cart": {
89+
"id": "Q2FydE5vZGU6MTIz",
90+
"numItems": 2,
91+
"totalInclTax": "59.98",
92+
"currency": "USD",
93+
"lines": {
94+
"edges": [
95+
{
96+
"node": {
97+
"id": "Q2FydExpbmVOb2RlOjE=",
98+
"quantity": 1,
99+
"product": { "title": "Premium Supplement" },
100+
"linePriceInclTax": "29.99"
101+
}
102+
}
103+
]
104+
}
105+
}
106+
}
107+
}
108+
```
109+
110+
## Common use cases
111+
112+
### Custom sidecarts
113+
114+
The most common use of the Storefront API is building custom sidecart experiences. Use `cart` queries to fetch the current cart state and render a fully custom cart drawer with your own markup, animations, and styling.
115+
116+
### Upsells and cross-sells
117+
118+
Add upsell products to the cart dynamically using mutations like `addCartLines`. Query the product catalog with `products` to find related items, then present them in your sidecart or on product pages.
119+
120+
```graphql title="Add an upsell to the cart"
121+
mutation AddUpsell($input: AddCartLinesInput!) {
122+
addCartLines(input: $input) {
123+
success
124+
cart {
125+
numItems
126+
totalInclTax
127+
}
128+
}
129+
}
130+
```
131+
132+
### User accounts
133+
134+
Handle customer registration and authentication directly from your storefront with `register`, `tokenAuth`, and `updateAccount` mutations.
135+
136+
### Vouchers and discounts
137+
138+
Apply and remove voucher codes from carts using `addVoucher` and `removeVoucher` mutations, enabling custom promo code UIs.
139+
140+
141+

‎content/docs/storefront/graphql/meta.json‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
{
2-
"title": "GraphQL Reference",
2+
"title": "GraphQL API",
33
"pages": [
4-
"index",
54
"queries",
65
"mutations"
76
]

‎scripts/generate-graphql-docs.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ Browse all available [Queries](/docs/storefront/graphql/queries) and [Mutations]
6868

6969
writeFileSync(join(GRAPHQL_DIR, 'meta.json'), JSON.stringify({
7070
title: 'GraphQL Reference',
71-
pages: ['index', 'queries', 'mutations'],
71+
pages: ['queries', 'mutations'],
7272
}, null, 2) + '\n');
7373

7474
// ── Step 3: Introspect schema ───────────────────────────────────────────────

‎tools/config.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
SITE_DOMAIN = "https://developers.29next.com"
1+
SITE_DOMAIN = "https://developers.nextcommerce.com"
22
BASE_API_FILES_PATH = "../public/api/"
33

44
CAMPAIGNS_API_SPEC_SOURCE = "https://campaigns.apps.29next.com/api/schema/"

0 commit comments

Comments
 (0)