Repository navigation
Development
Start with Getting Started to get the app and its local stack running.
| Script | Does |
|---|---|
pnpm dev |
Runs the app at http://localhost:3000 |
pnpm build |
Builds the app into .output/
|
pnpm preview |
Serves the built app |
pnpm test |
Every test: the unit tests and the Storybook stories |
pnpm test:unit |
Unit tests (Vitest); the database tests run too once the stack's settings are loaded (below) |
pnpm storybook |
Storybook at http://localhost:6006 |
pnpm test:storybook |
Every story as a test, in light and dark (below) |
pnpm build-storybook |
The static Storybook, in storybook-static/
|
pnpm typecheck |
Type-checks the app (nuxt typecheck, TypeScript 6) and each package (TypeScript 7) |
pnpm lint / pnpm format
|
Biome: checks, or fixes and formats |
pnpm db:generate |
Writes a migration after a change to server/db/schema.ts
|
pnpm db:migrate |
Applies the migrations to DATABASE_URL (scripts/migrate.ts) |
-
Game rules (
packages/core) and input and camera math (packages/game) are plain unit tests. -
Database tests (
server/utils/*.test.ts) run against the local stack. WithoutDATABASE_URLthey're skipped. With it, Vitest migrates the database once (server/db/migrate.setup.ts).- The progress tests record bests for guests in the local user pool.
- The levels tests replay a known solution for every level in Postgres.
Load the stack's settings, then test:
set -a; . ./.env; set +a
pnpm test:unitCI does the same, against a fresh stack.
- Edit
server/db/schema.ts. - Run
pnpm db:generateand review the SQL it writes toserver/db/migrations/. - Run
pnpm db:migrate, orpnpm exec spotcraft dev, which migrates too.
Migrations only ever add. During a release the old and new versions both run for a few seconds, and a rollback runs an older image against a newer database. Renaming or dropping something needs its own plan (Deploying on Spotcraft). Don't edit a migration once it's been applied.
Levels live only in Postgres, so a collection is a migration.
-
Make an empty custom migration:
pnpm exec drizzle-kit generate --custom --name <collection>
-
Fill it from a plain-text XSB file. The script parses every level with the game's own parser first:
node scripts/import-collection.ts <collection>.txt server/db/migrations/<file>.sql \ --id <slug> --title "<Title>" --order <n> --author "<Author>" --credit "<Credit>"
-
Migrate, then add a solution for each new level to
server/utils/solutions.json, with the dev server running:curl -s localhost:3000/api/levels | node scripts/solve-levels.ts server/utils/solutions.json -
Run the database tests: every level must replay its solution.
Only add levels whose terms allow it, and keep their credit (the README lists the current ones).
Storybook documents the components and tests them. It runs inside the Nuxt app (@storybook-vue/nuxt), so auto-imports, color mode and Tailwind work in stories.
-
Where things are: stories live in
stories/:ui/for the shadcn-vue primitives,app/for Sokobanko's components, anddocs/for the Introduction and the design tokens (colours, type, sizing, the board's pieces). Level fixtures are instories/fixtures/levels.ts. Stories stay out ofapp/components, because Nuxt would register them as components there. -
Toolbars: Theme switches light and dark (the
darkclass on<html>, as color mode sets it), and Viewport switches phone and desktop. -
Leaving out: components that read the TanStack collections or the server (the pages,
ProgressSync) aren't storied.
pnpm test:storybook runs each story in headless Chromium twice, in light and in dark: the Vitest projects storybook-light and storybook-dark, in vitest.config.ts. A story fails if:
- it doesn't render;
- its
playfunction fails: the clicks, keys and emitted events it checks; - axe finds a violation. Every story runs with
a11y: { test: "error" }. To turn off one rule for one story, explain why in a comment, as the open dropdown menus do; - its screenshot differs from its baseline in
__screenshots__/, next to the story file.
-
Linux only: baselines are rendered on CI's Linux Chromium, and only compared there; fonts render differently on a Mac. A local run checks everything else.
VISUAL=1forces the comparison anywhere. -
What's captured: the whole page, in each theme, so dialogs and menus portalled to
<body>are included. On the test page, animations finish at once (.storybook/vitest.html). -
Opting out: a story opts out with
parameters: { visual: false }. The PixiJS board does, because screenshots don't capture its WebGL canvas.
After an intended visual change, CI's storybook job fails, and its screenshot-diffs artifact holds the actual and diff images. To take new baselines:
gh workflow run update-screenshots.yml --ref <branch>
gh run download <run id> -n screenshots -D storiesReview the images, then commit them (signed) with the change. A new story's first CI run also writes its baseline into screenshot-diffs.
-
Biome formats and lints everything except Markdown, the lockfile and the generated shadcn-vue components (
app/components/ui). -
TypeScript is strict, including
noUncheckedIndexedAccessandexactOptionalPropertyTypes. -
UI components come from shadcn-vue (
components.json) and are styled with the tokens inapp/assets/css/main.css.
The coding agents' skills (Nuxt, Vue, PixiJS, shadcn-vue and others) aren't committed. skills-lock.json lists them, and this restores them into .agents/skills:
npx skills experimental_installTwo skills are committed instead, in .claude/skills/: commit-message and github-workflows, Sokobanko's copies of the ecosystem's shared skills.