Quick Start

One command. 30 seconds. A working Cloudflare Worker on your machine. No Cloudflare account needed to start.

npm create wrangler-deploy@latest my-app

That scaffolds a hello-world Worker, installs dependencies, and prints the dev command. After it finishes:

cd my-app
pnpm dev

Open http://localhost:8787 — you’ll see JSON. That’s the entire day-1 path.

Deploying to Cloudflare is a second step, on your terms. We get there in Step 4.

Step 1 — Scaffold

$ npm create wrangler-deploy@latest my-app

  Created hello starter in /now/my-app
    ✓ package.json
    ✓ tsconfig.json
    ✓ src/index.ts
    ✓ wrangler.jsonc
    ✓ wrangler-deploy.config.ts
    ✓ README.md
    ✓ .gitignore

  Installing dependencies with pnpm...
  …
  ✓ Ready.

  Start dev:
    cd my-app && pnpm dev

  Then open http://localhost:8787 — you should see JSON.

  When you're ready to put it on the edge:
    cd my-app && pnpm deploy

pnpm, yarn, and bun all work too — same line, swap npm for your tool. The scaffolder detects which one you used and installs dependencies with it.

Pass --no-install if you’d rather install dependencies yourself.

Step 2 — Local dev

$ cd my-app
$ pnpm dev

 ⛅️ wrangler 4.91.0
───────────────────
⎔ Starting local server...
[wrangler:info] Ready on http://localhost:8787

Open the URL. You should see:

{
  "message": "Hello from Cloudflare Workers!",
  "path": "/",
  "now": "2026-05-14T20:00:00.000Z"
}

Edit src/index.ts, save — wrangler dev hot-reloads on every save.

Step 3 — When you need more

The scaffolder gives you the bare minimum on purpose. Add things as you need them:

Want	Do
A KV namespace, D1 database, or queue	Add it to wrangler-deploy.config.ts — see Resources
A frontend (Hono API + Vite)	npm create wrangler-deploy@latest my-app -- --template vite
A React + Vite + Workers starter	npm create wrangler-deploy@latest my-app -- --template react
Any Cloudflare template from GitHub	npm create wrangler-deploy@latest my-app -- --example github:user/repo/path
Multiple workers in one repo	Add more paths to workers in the config
Editor / agent hints	wd create vibe-rules claude-code,cursor

Interactive picker

Run without a template name on a TTY and you’ll get an arrow-key picker:

$ npm create wrangler-deploy@latest

✨ wrangler-deploy — scaffold a new Cloudflare Workers project

◇  Project name (used as the directory)
│  my-worker
│
◆  Pick a template
│  ● hello — Bare hello-world Worker (fastest, recommended for beginners)
│  ○ vite — Hono API + Vite frontend + typed KV binding
│  ○ react — React + Vite + Workers (official Cloudflare scaffold + wrangler-deploy migration)
│
└  Scaffolding hello into ./my-worker…

In CI / non-TTY contexts the picker is automatically skipped and defaults are used. Pass --yes to force-skip prompts anywhere.

Step 4 — Deploy to the edge

This is the Cloudflare moment. You’ll need an account; if you don’t have one yet, sign up at dash.cloudflare.com/sign-up.

$ pnpm run deploy
# or: npm run deploy, yarn run deploy, bun run deploy

The first time you run it, Wrangler opens a browser tab to authenticate you. After that it’s just a deploy — your Worker is live on *.workers.dev in a few seconds. For the hello-world template, pnpm run deploy is a thin alias for wrangler deploy; no stages, no apply step, no extra concepts.

pnpm gotcha

Use pnpm run deploy, not pnpm deploy. pnpm deploy is a built-in pnpm workspace command and won’t run the script.

Dry-run tip

If you need a true Wrangler deploy preview, run wrangler deploy --dry-run directly (or npx wrangler deploy --dry-run) from the project directory.

When you outgrow a single deploy

As soon as you add a KV namespace, D1 database, or queue to wrangler-deploy.config.ts, you’ll want stages — separate copies of your stack for staging, pr-123, etc. That’s where the wd workflow shines:

$ wd plan --stage staging      # see what would be created
$ wd apply --stage staging     # provision resources (KV, D1, queues)
$ wd deploy --stage staging    # deploy workers in dependency order
$ wd status --stage staging    # confirm everything is live
$ wd destroy --stage staging   # tear it all down

Stages get suffixed automatically: payments-db becomes payments-db-staging, your Worker becomes my-app-staging. Production stays untouched.

Already have a Wrangler project?

If your repo already has wrangler.jsonc files, skip the scaffold and generate the wrangler-deploy config from what you have. Your Wrangler files are not modified.

$ wd init

  Generated wrangler-deploy.config.ts from /repo

  Next:

    wd context set --stage <name>   Set default stage
    wd plan                         Preview what will be created
    wd apply                        Provision resources
    wd deploy                       Deploy workers
    wd status                       Verify everything is live

If your resources already exist in your Cloudflare account, use wd introspect instead — it generates config from the live account.

From here the four-step staged-deploy flow (plan → apply → deploy → destroy) is the same as the fresh-scaffold path above. See Step 4 for the one-liners and the CLI reference for the full output of each command.

Going further with wd dev

For multi-worker repos, wd dev starts every worker together, resolves ports automatically, and supports dependency-aware filtering and Queue local-dev sessions. The hello-world scaffold uses plain wrangler dev because there’s only one worker; once you add more, swap to wd dev.

$ wd dev

  wd dev — 3 workers
  workers/api            → http://localhost:8787
  workers/batch-workflow → http://localhost:8788
  workers/event-router   → http://localhost:8789

For Queue local-dev (producer + consumer sharing one Miniflare environment):

$ wd dev --session --persist-to .wrangler/state

For broader local workflows (dashboard, fixtures, queue sends, D1 exec, cron triggers, verify packs), see the CLI reference and the Dev UI guide. A few highlights:

$ wd dev doctor                      # preflight checks
$ wd dev ui --port 8899              # local runtime dashboard
$ wd worker call workers/api --path /health
$ wd queue send payment-outbox --json '{"type":"batch.dispatched"}'
$ wd cron trigger workers/batch-workflow --port 8787
$ wd verify local --pack smoke

The core model

• Keep wrangler.jsonc for development — Wrangler stays your authoring surface.
• Add wd dev --session when you need one shared Miniflare environment for Queues.
• Generate stage-aware rendered JSONC for deploys — never edit those files by hand.
• One project-level config (wrangler-deploy.config.ts) connects the two.

Troubleshooting

Problem	Fix
wd <anything> fails with WD_E_CONFIG_MISSING	Run wd init (existing repo) or npm create wrangler-deploy@latest <name> (fresh).
Cannot find package 'wrangler-deploy' after scaffold	Run pnpm install (or npm install) in the new directory. The scaffolder normally does this for you — pass --no-install to skip it.
WD_E_AUTH_FAILED on apply/deploy	Run wd login, or set CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID.
WD_E_ACCOUNT_MISMATCH (Cloudflare error 10000)	Your API token does not belong to CLOUDFLARE_ACCOUNT_ID. Fix one of them.
WD_E_STATE_MISSING on deploy/status	Run wd apply --stage <name> first.
Default stage warning on every command	Pin it with wd context set --stage <name>.

Every error code is described by wd explain <code>. To explain the most recent failure: wd explain --from-last-error.

Next steps

• How it works — the architecture in one page
• CLI reference — every command with example output
• Config reference — the full wrangler-deploy.config.ts schema
• PR preview environments — one-command-per-PR stage lifecycle