Skip to content
Quarry Docs

Runbook: Local development

Get the next-gen quarry.team running locally.

Prerequisites

Section titled “Prerequisites”
  • Node.js — use the version pinned in .nvmrc (24, the current LTS line). engines requires node >= 22.12.0. With nvm: nvm use.
  • pnpm — this repo pins pnpm@10.14.0 via packageManager (Corepack will honor it). engines requires pnpm >= 9. Enable Corepack with corepack enable if needed.
  • Git, and a clone of quarry-design-group/quarry.team.

First-time setup

Section titled “First-time setup”
Terminal window
# from the repo root
pnpm install            # installs all workspaces (frozen lockfile in CI)
pnpm tokens             # build design tokens: tokens.json -> tokens.css

pnpm install runs husky to set up git hooks (prepare). lint-staged will lint/format staged files on commit.

Running the site

Section titled “Running the site”
Terminal window
pnpm dev                # @quarry/web Astro dev server
pnpm dev:docs           # @quarry/docs (apps/docs) dev server

Open the URL Astro prints. Editing content in apps/web/src/content or components hot-reloads.

Common scripts

Section titled “Common scripts”
Command What it does
pnpm dev Run the web app dev server (@quarry/web)
pnpm build Build tokens (@quarry/ui) then the web app (@quarry/web)
pnpm build:web / pnpm build:docs Build a single app
pnpm preview Preview the production web build locally
pnpm tokens Rebuild design tokens (tokens.json → tokens.css)
pnpm typecheck TypeScript strict + astro check, all packages
pnpm lint ESLint (cached)
pnpm format / pnpm format:check Prettier write / check
pnpm test Vitest unit tests (@quarry/web)
pnpm test:e2e Playwright end-to-end tests

Editing design tokens

Section titled “Editing design tokens”

Tokens are the source of truth (ADR 0003). Edit packages/ui/tokens/tokens.json, then pnpm tokens to regenerate tokens.css. Never hand-edit tokens.css — it is generated and CI checks it is fresh.

Before you push

Section titled “Before you push”
Terminal window
pnpm typecheck && pnpm lint && pnpm format:check && pnpm test

This mirrors the core CI validate gates (ADR 0009) and saves a round trip. See ../../CONTRIBUTING.md for branch and commit conventions.

Troubleshooting

Section titled “Troubleshooting”
  • Type errors about content frontmatter → a Zod schema mismatch; fix the frontmatter (see content authoring guide).
  • tokens.css shows as changed in git unexpectedly → run pnpm tokens and commit the regenerated file; don’t edit it by hand.
  • Wrong Node/pnpm version → nvm use; corepack enable.
  • Playwright “browser not installed” → run pnpm exec playwright install.