How this handbook works

This is a VitePress site: every page is a Markdown file under docs/. You read it in the browser; Claude edits the Markdown.

Asking for updates

Open Claude Code in the shopify research folder and ask things like:

• "Add a page on Shopify Functions with a discount example."
• "Explain token exchange in more depth on the auth page, with a diagram."
• "I don't understand usage-based billing — add a worked example."
• "Add a quiz at the end of the webhooks page."

Claude updates or adds the page, adds it to the sidebar, and logs the change in What changed so the team can see what's new.

Running it locally

npm run dev

Opens at http://localhost:5179. Pages reload as soon as a file changes.

Sharing with the team

npm run build

Produces a static site in docs/.vitepress/dist — upload that folder to any static host (Vercel, Netlify, GitHub Pages, Cloudflare Pages, or an S3 bucket). Every teammate then reads the same version.

Page conventions

Marker	Meaning
::: tip	A shortcut or good habit
::: warning	A common mistake or a review-rejection risk
::: danger	Something that breaks in production or loses money
::: details	Deeper material you can skip on first read
Check yourself	A few questions at the end of each page

Shopify changes fast

Shopify ships a new API version every quarter and retires old patterns regularly. Each page links to the official docs; when the handbook and shopify.dev disagree, shopify.dev wins — and tell Claude so the page gets fixed.