Skip to content

Local development

wrangler dev runs the Worker on your machine with local stand-ins for D1 and R2, so you can work on DragonslairCMS without touching your deployed site.

You need Node.js 20 or later (.nvmrc pins 22, so nvm use picks it up).

Terminal window
npm install
npm run db:schema # create the local D1 schema
npm run dev # wrangler dev

Open the local address Wrangler prints (normally http://localhost:8787), go to /admin, and you’re sent to /admin/setup to create the first admin. That’s all the configuration there is: the local database mints its own session secrets, separate from your deployed site’s.

npm run db:schema is safe to run again at any time; see Database and schema changes.

Script Runs What it does
npm run dev wrangler dev Runs the Worker locally
npm run db:schema wrangler d1 execute DB --file=schema.sql --local --yes Applies the schema to the local database
npm run db:schema:remote the same with --remote Applies the schema to the deployed database
npm run deploy npm run db:schema:remote && wrangler deploy Applies the schema remotely, then deploys
npm run setup node scripts/setup.js The guided first install (Installation)
npm test node --test "tests/*.test.js" Runs the unit tests in tests/ with Node’s built-in test runner

The db:* scripts address the DB binding rather than a database name, so they work whatever you’ve called your database.

Wrangler keeps the local database and bucket in .wrangler/ in the project folder (it’s gitignored). Uploads go to the local bucket, not your real one.

To look at the local database:

Terminal window
npx wrangler d1 execute DB --local --command "SELECT id, slug, status FROM pages"

To start again from nothing, stop wrangler dev, delete the .wrangler/state folder, and run npm run db:schema again.

You don’t need any secrets locally. If you want sessions to survive a database reset, copy .dev.vars.example to .dev.vars and uncomment and fill in ADMIN_SESSION_SECRET and READER_SESSION_SECRET (32 or more random characters each). .dev.vars is gitignored. Use wrangler secret put, not this file, for the deployed Worker. See Session secrets.

Real email isn’t delivered from a local run. Turn Send outgoing email off in the local admin’s Settings to use the no-email flows, which is also the easiest way to test them. To exercise the email flows instead, set Site URL (canonical) to http://localhost:8787: plain http:// is accepted only for loopback addresses like this. See Email.

The Cron Trigger doesn’t fire during wrangler dev. To run the scheduled handler by hand:

Terminal window
npx wrangler dev --test-scheduled
# in another terminal:
curl "http://localhost:8787/__scheduled?cron=*/15+*+*+*+*"

Any scheduled article whose time has passed is published, and Wrangler’s output logs [schedule] published 1 article(s).

  • The session cookies are marked Secure. Chrome and Firefox accept them on http://localhost; if a browser keeps sending you back to the login page, try another one.
  • /theme.css is cached for 60 seconds, so theme changes can take a minute to appear, locally as well.
  • There’s no build step. Wrangler reloads when you save a file in src/ or public/.