Build your first theme

You need Node 22.12 or later. Each step prints what it did — read the output before moving on.

Create the theme

Create a theme called my-theme

npm create @usequeek/theme@latest my-theme

It asks for the theme's name, the templates it is dressed as, its tags, extra pages and your AI assistants. Every prompt is also a flag, so the whole thing can be scripted:

Create without prompts

npm create @usequeek/theme@latest my-theme -- --templates laundry --tags minimal --yes

It prints the folder it wrote. Inside is your theme (theme/), the contract it is checked against (docs/THEME.md), and npm scripts for every step below.

Preview it

Start the preview

npm run dev

It prints a Preview URL starting at port 7833 (the next free port up from there if 7833 is busy). Open it. Every page of every demo store is there, and edits reload the page.

Your theme lives in theme/: layout, header, footer, blocks, pages, shells, plus manifest.ts, theme.config.ts and demo.json. Replace the design. Keep the contract — the files and what each one must do are in How themes work.

Run the check until it is clean

Check against the contract

npm run check

Right after create, the check prints your to-do list, not faults: replace the placeholder products and photos, write each template's description, capture screenshots, and — with two or more templates — give each design its own home page. Work until it reports no errors. If your theme prints its own words instead of hard-coding them, see Translating your theme.

Capture screenshots

Screenshot every design

npm run screenshot

It prints one line per file it wrote, then suggests running the check. Each design's first screen lands at 1280×800 — the main one as theme.jpg, the rest beside their demo files.

Package and submit

Build the submission zip

npm run package

It prints the zip path and size, and warns if any error would block submission. Send the zip as described in Submit your theme.