Setting up & deploying Cloudflare Workers with Wrangler

Before creating a Worker project, install the following on your machine:

• npm — Node's package manager, used to install and run project tooling.
• Node.js — the JavaScript runtime that npm and Wrangler run on top of.

npm create cloudflare

Scaffolds a new Cloudflare Worker project, including the base folder structure and starter files.

npx wrangler

Lists the commands available in Wrangler, Cloudflare's CLI for building, testing, and deploying Workers.

npx wrangler login

Grants Wrangler access to your Cloudflare account by opening a browser window to complete authentication.

npx wrangler whoami

Verifies which Cloudflare account you're currently logged in with — useful if you manage more than one account.

npm run deploy

Deploys your code to Cloudflare's network. Run this from inside the project directory that holds your deployment files (the folder containing wrangler.toml/wrangler.json and your package.json).

Wrangler lets you build and test your Worker on your machine before pushing it live, so you can catch issues before deployment.

npm start

Starts a local development session so you can preview your Worker at localhost.

Test changes by editing the index.ts file, typically located inside the src directory of your project. Once you save the file, refresh the browser tab and your update should appear.

While npm start is running, press l on the same page to switch out of local mode and preview how the Worker behaves when it's actually running on Cloudflare's live infrastructure.

• Open DevTools, go to the Network tab, and click the request for your Worker.
• Check the Response Headers — you should see a cf-ray header, Cloudflare's unique request identifier for that call.

Once npm run deploy finishes, confirm the live version is actually working before you consider the job done:

• Open the URL returned in your terminal (e.g. https://your-worker.your-subdomain.workers.dev) and confirm it matches what you tested locally.
• Stream real-time logs from the live Worker to watch for runtime errors:

npx wrangler tail

Leave this running while you exercise the live endpoint — request logs, exceptions, and console.log output stream to your terminal as they happen.

After Step 2, npm create cloudflare scaffolds a project with roughly this layout:

my-worker/
├── src/
│   └── index.ts        # Worker entry point (edited in Step 8)
├── test/               # Sample tests for the Worker
├── wrangler.json       # Wrangler configuration (or wrangler.toml)
├── package.json        # npm scripts and dependencies
└── tsconfig.json       # TypeScript configuration

The two files to know first are src/index.ts, where your Worker's logic lives, and wrangler.json/wrangler.toml, which controls how the project builds and deploys (see toml vs. json below).

Don't put API keys, tokens, or other sensitive values directly in wrangler.toml/wrangler.json — those files are typically checked into version control. Use secrets instead:

npx wrangler secret put API_KEY

Wrangler prompts you to paste the value, then encrypts and stores it on Cloudflare's side. It's available in your Worker via env.API_KEY but never appears in your source files or config.

Non-sensitive configuration (feature flags, environment names, public URLs) can go in the vars section of your Wrangler config file instead, since those values are fine to commit.

By default, a deployed Worker is reachable at a *.workers.dev subdomain. To serve it from your own domain, attach a route or custom domain in your Wrangler config:

{
  "routes": [
    { "pattern": "example.com/api/*", "zone_name": "example.com" }
  ]
}

Or, for a dedicated subdomain fully managed by Cloudflare:

{
  "routes": [
    { "pattern": "api.example.com", "custom_domain": true }
  ]
}

The domain must already be onboarded to Cloudflare (using Cloudflare nameservers) before you can attach a route. Redeploy with npm run deploy after updating the config for the change to take effect.

If a deployment introduces a regression, you can revert to the previous version without redeploying old code by hand:

npx wrangler rollback

This reverts the live Worker to the last known-good deployment. Use npx wrangler deployments list first if you need to see history and pick a specific version to roll back to.

Wrangler and npx are directory-aware — they read the wrangler.jsonc (or wrangler.toml) file from whatever directory you're in. That one file defines the project name, D1 bindings, worker entry point, secrets, and every other project-specific setting. There is no global project state. The golden rule: confirm your directory before running any command.

Three commands to run before every session

These take under ten seconds and prevent accidental cross-project changes:

pwd                              # which directory am I in?
cat wrangler.jsonc | grep '"name"'   # does the project match the client?
npx wrangler whoami              # which Cloudflare account is authenticated?

Switching between client projects

# Move to client A and confirm
cd ~/Projects/client-a
pwd
cat wrangler.jsonc | grep '"name"'
npm run dev              # runs only for client-a

# Switch to client B
cd ~/Projects/client-b
pwd
cat wrangler.jsonc | grep '"name"'
npm run dev              # runs only for client-b

Each directory has its own node_modules, its own wrangler.jsonc, and its own D1 database IDs. Nothing bleeds between projects.

Recommended folder structure

~/Projects/
  client-a/
    wrangler.jsonc     ← name: "client-a-app"
    src/index.js
    public/index.html
    .dev.vars          ← local secrets (never commit)
    schema.sql
  client-b/
    wrangler.jsonc     ← name: "client-b-app"
    src/index.js
    public/index.html
    .dev.vars
    schema.sql

Each project is self-contained. The .dev.vars file holds secrets for local development only — add it to .gitignore so it's never committed:

echo ".dev.vars" >> .gitignore

Commands that affect production vs. local only

Always confirm your directory and project name before running anything in the left column:

Show the full path in your terminal prompt

Add this to your ~/.zshrc so your current directory is always visible — you can't accidentally run a command in the wrong location:

export PS1="%F{green}%~%f %% "

Apply it immediately without restarting your terminal:

source ~/.zshrc

Switching Cloudflare accounts between clients

If different clients use different Cloudflare accounts, log out of the current account and into the correct one before any deployment or database command:

npx wrangler logout
npx wrangler login
npx wrangler whoami

Confirm the account name matches the client before proceeding.

Sign out of Wrangler when you finish a session — especially on a shared or temporary machine, or when switching between client Cloudflare accounts:

npx wrangler logout

This revokes the local OAuth token created in Step 4, so the machine no longer has standing access to your Cloudflare account. The token is stored at:

~/.wrangler/config/default.toml

After logging out, the next command that requires authentication prompts you to run npx wrangler login again.

Full account switch sequence

Use this when moving between client accounts to ensure you're always authenticated as the correct user:

npx wrangler logout
cd ~/Projects/client-b
npx wrangler login
npx wrangler whoami

The final whoami confirms the new account is active before you run anything that touches production.

All commands below are safe to run locally. None touch your production worker, remote database, or account settings unless the --remote flag is explicitly present.

Starting and stopping the local server

Local D1 database commands

Secrets and environment variables

# Example .dev.vars file
ADMIN_PIN=your-local-pin
API_KEY=your-local-api-key

echo ".dev.vars" >> .gitignore

Logs and debugging

Types and configuration

Quick reference — safe vs. production-affecting

Both ship with Node.js, but they solve different problems: one manages dependencies your project keeps, the other runs tools you don't need to keep.

Compatibility date error

The Worker requires compatibility date "xxxx-yy-zz", but the newest
date supported by this server binary is "xxxx-yy-zz".
✘ [ERROR] The Workers runtime failed to start. There was likely a
problem with the workerd binary or your configuration.

Fix: update the compatibility date in your project's Wrangler config file.

• Open wrangler.json (or wrangler.toml) in your project directory.
• Update the value: "compatibility_date": "xxxx-yy-zz"
• Save the file.
• Restart the local Worker session: npm start

Critical fields in the Wrangler config file