How to Set Up Wrangler for Cloudflare Workers Development

Why Wrangler

Wrangler is Cloudflare’s CLI for Workers and Pages. It authenticates, runs a local dev server, manages secrets and KV bindings, and deploys — all from the terminal.

Step 1 — Install and log in

npm install -g wrangler
wrangler login

The login opens a browser to authorize the CLI. After it completes, your API token is cached locally (never commit it).

Step 2 — Initialize a Worker project

mkdir my-worker && cd my-worker
npm init -y
npm install -D wrangler
npx wrangler init

This generates wrangler.toml:

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-08-17"

[[kv_namespaces]]
binding = "CACHE"
id = "your-namespace-id"

Step 3 — Run the dev server

npx wrangler dev

This runs your Worker at http://localhost:8787 with live reload. Local secrets go in .dev.vars (gitignored):

MY_SECRET="local-only-value"

Step 4 — Use a KV binding

src/index.ts:

export default {
  async fetch(request: Request, env: { CACHE: KVNamespace }): Promise<Response> {
    const count = (await env.CACHE.get("visits")) || "0";
    const next = String(Number(count) + 1);
    await env.CACHE.put("visits", next);
    return new Response(`visits: ${next}`);
  },
};

Read the binding with env.CACHE — the name must match the binding in wrangler.toml, not the namespace’s display name.

Step 5 — Deploy

npx wrangler deploy

Secrets are stored server-side, never in wrangler.toml:

npx wrangler secret put MY_SECRET

Troubleshooting

• wrangler: command not found — run via npx wrangler or check your global npm bin is on PATH.
• Binding is undefined at runtime — the binding key in wrangler.toml must exactly match the env property name in code.
• Local secrets missing — wrangler dev reads .dev.vars; dashboard secrets only appear after wrangler secret put.

Summary

You can now develop Workers locally with hot reload, keep secrets out of Git via .dev.vars, use KV bindings, and deploy with one command.