Every script in package.json, run from the starter root. This page is generated from package.json and the commands table in AGENTS.md, so it lists every script that exists and nothing else. pnpm exec wrangler … runs the pinned wrangler for anything the scripts do not cover.
Develop and build
Section titled “Develop and build”The ones you run every day.
| Command | Runs | What it does |
|---|---|---|
pnpm dev |
tsx scripts/dev-setup.ts && astro dev |
scripts/dev-setup.ts first (writes .env from .env.example when missing, applies the D1 migrations to the local Miniflare database, seeds the demo dataset with its logos while that database is empty, and stops if a .dev.vars from an older copy is still there), then the Astro dev server. No Pagefind index, no OG images on disk. ZERODIRS_SKIP_DEV_SETUP=1 skips the setup |
pnpm build |
astro build |
Full static build + sitemap + Pagefind + budget + SEO report |
pnpm preview |
astro preview |
Serve the built output. Its Worker has the secrets .env held at build time (snapshotted into dist/server/.dev.vars), plus .env as Astro loads it into process.env; after editing .env, build again |
pnpm deploy |
astro build && wrangler deploy |
astro build && wrangler deploy |
Check and test
Section titled “Check and test”pnpm check is the gate before a push: the GitHub Actions deploy runs it again and refuses to ship what it fails.
| Command | Runs | What it does |
|---|---|---|
pnpm check |
astro check && tsc -p tests/workers/tsconfig.json && tsx scripts/check-config.ts |
astro check, then tests/workers/ types, then pnpm check:config. The gate |
pnpm check:config |
tsx scripts/check-config.ts |
Validate site.config.ts alone and print the file-count estimate |
pnpm test |
vitest run -c vitest.config.ts |
Vitest unit suite |
pnpm test:e2e |
tsx scripts/dev-setup.ts && playwright test |
scripts/dev-setup.ts (migrations, and the demo seed while the local database is empty), then the Playwright smoke tests against the built site (builds first only when dist/ is stale) |
pnpm test:workers |
vitest run -c vitest.workers.config.ts |
Vitest inside workerd, against the real DB / MEDIA bindings (tests/workers/) |
pnpm lhci |
lhci autorun --config=lighthouserc.cjs |
Lighthouse CI against lighthouserc.cjs |
Content
Section titled “Content”The demo data and the seed datasets, moving listings in and out of the database, and the site’s own share image.
| Command | Runs | What it does |
|---|---|---|
pnpm content:reset |
tsx scripts/content.ts reset |
Delete the demo data from a database: the seeded rows, their logos in the bucket, the demo blog posts (--yes; --local by default, --remote). Leaves the database empty |
pnpm content:use |
tsx scripts/content.ts use |
Seed a database with a dataset from seed/datasets/ — rows and logos — and copy its blog posts into src/content/blog/ (--yes; --local by default, --remote) |
pnpm listings:import |
tsx scripts/import.ts |
CSV/JSON → rows in a database (--local or --remote, one is required unless --dry-run; --map) |
pnpm listings:export |
tsx scripts/export.ts |
D1 → seed/.out/export/*.md, the same format listings:import reads |
pnpm og:default |
tsx scripts/og-default.ts |
Regenerate public/og-default.png from site.config.ts (--check to verify) |
Database
Section titled “Database”The D1 database behind submissions, accounts and the review queue. Local is the Miniflare copy under .wrangler/; remote is the real one.
| Command | Runs | What it does |
|---|---|---|
pnpm db:generate |
drizzle-kit generate |
drizzle-kit: src/db/schema.ts → the next migration. First one: --name init |
pnpm db:migrate:local |
wrangler d1 migrations apply DB --local |
Apply pending migrations to the Miniflare database under .wrangler/ |
pnpm db:migrate:remote |
wrangler d1 migrations apply DB --remote |
Apply them to the real D1 database |
pnpm db:seed:local |
tsx scripts/seed.ts --local |
A dataset’s Markdown listings → the local D1 (--dataset, default ai-tools; --from for any directory; --with-favicons, --with-images store the logos in the bucket). Replaces only rows with source = 'seed' |
pnpm db:seed:remote |
tsx scripts/seed.ts --remote |
The same, against the real database. Run it once: only D1 enforces the size limits |
Cloudflare
Section titled “Cloudflare”Going live, and keeping the deployed Worker in step with the repository.
| Command | Runs | What it does |
|---|---|---|
pnpm cf:doctor |
tsx scripts/cf-doctor.ts |
Read-only: what is wired up and what is not — tooling, site.config.ts, wrangler.jsonc, .env, the secrets the Worker holds, the R2 bucket and sending domain, and whether the live site was built with this config. Every line that is not ok carries the command that fixes it. --offline skips anything needing a login, --json for an agent, --strict fails on warnings, --manual lists the steps no CLI can do |
pnpm cf:typegen |
wrangler types --env-file .env.example |
Regenerate worker-configuration.d.ts after editing wrangler.jsonc or adding a key to .env.example. The secret names come from .env.example, never from your .env, so the file is the same on every machine; pnpm cf:typegen --check is what CI runs |
pnpm cf:secrets |
tsx scripts/put-secrets.ts |
Send every runtime secret in .env.prod to the Worker in one wrangler secret bulk, then read back what the Worker has and what site.config.ts still needs. Checks each value’s shape first, refuses placeholders and unknown keys, never echoes a value; there is no fallback to .env. --dry-run shows the plan without sending; --list shows the names, their help text and what is set; bare names (pnpm cf:secrets STRIPE_WEBHOOK_SECRET) send only those |
pnpm cf:ci |
tsx scripts/cf-ci.ts |
Push the build-time half of .env.prod (or .env) to GitHub Actions — gh variable set or gh secret set per the # ci: line in .env.example — and rewrite the Build step’s env: block in .github/workflows/deploy.yml so a new variable cannot be forgotten. --enable turns the workflow on, --dry-run prints the plan |
pnpm cf:setup |
tsx scripts/cloudflare-setup.ts |
From this checkout to a running site on Cloudflare: names the Worker after the site, binds site.url as a custom domain (--workers-dev for *.workers.dev), creates the D1 database and R2 bucket, leaves out the send_email binding until the account has a sending domain, migrates the production database, builds, deploys, and sets TOKEN_SECRET. Idempotent; --dry-run prints the plan; --yes skips the confirmation |
pnpm cf:media |
tsx scripts/cf-media.ts |
Make the R2 bucket readable from the web — a custom domain when you have the zone id, the rate-limited r2.dev URL otherwise — and write the result into media.baseUrl in site.config.ts, restoring the file if the edit does not validate. --dev-url skips the domain, --force replaces a media.baseUrl that is already set |
Agent skills
Section titled “Agent skills”The skills in .agents/skills/ are copied to .claude/skills/ so Claude Code and Codex both find them.
| Command | Runs | What it does |
|---|---|---|
pnpm skills:sync |
tsx scripts/sync-skills.ts |
Copy .agents/skills/ → .claude/skills/ |
pnpm postinstall |
tsx scripts/sync-skills.ts || true |
Runs pnpm skills:sync after pnpm install; a failure is ignored. Not meant to be run by hand. |
Related
Section titled “Related”- Project structure: where each script’s subject lives.
- Quickstart: the first three of these, in order.
- Go live: what
pnpm cf:setupdoes, step by step.