Cloudflare Workers run your code on Cloudflare’s global network. The Wrangler CLI is the main tool to develop, test, and deploy them from your terminal.

Prerequisites

• A Cloudflare account
• Node.js (LTS is fine)
• npm, pnpm, or yarn

Install Wrangler

Install Wrangler globally or as a dev dependency in your project:

npm install -D wrangler

Or with pnpm / yarn if you prefer. You can also use npx wrangler without a global install.

Log in once so Wrangler can talk to your account:

npx wrangler login

This opens a browser flow to authorize the CLI.

Create a new Worker

Scaffold a minimal Worker:

npx wrangler init my-worker
cd my-worker

Pick the starter you want (e.g. “Hello World” JavaScript or TypeScript). You’ll get an entry file (often src/index.ts or src/index.js) and a config file.

Configuration: wrangler.toml or wrangler.json

Wrangler reads wrangler.toml (or wrangler.json / wrangler.jsonc in newer setups). At minimum you usually set:

• name – Worker name in the dashboard
• main – path to your entry module
• compatibility_date – Workers runtime compatibility (use a recent date from the docs)

Example wrangler.toml:

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2025-01-01"

[vars]
ENVIRONMENT = "production"

Use [vars] for non-secret configuration. For API keys and tokens, use secrets (below), not plain vars in the repo.

Run locally

Start the dev server with hot reload:

npx wrangler dev

By default this binds to a local URL and proxies requests through the Workers runtime so behavior is close to production. You can pass --remote to run against Cloudflare’s edge while still developing (useful for some bindings).

Deploy

When you’re ready to publish:

npx wrangler deploy

Wrangler uploads your bundle and updates the Worker. The command output includes your Worker’s *.workers.dev URL (if enabled) or confirms the route you configured.

Custom routes and zones

To run on your own hostname, configure routes or workers_dev in wrangler.toml and ensure the zone is on Cloudflare. See Routes and domains in the docs.

Secrets

Never commit API keys. Store them as encrypted secrets:

npx wrangler secret put MY_API_KEY

You’ll be prompted to paste the value. In code, read it from the environment your handler receives (e.g. env.MY_API_KEY in the Workers fetch handler).

List secrets (names only) in the dashboard or via Wrangler where supported.

Environments (staging vs production)

You can define [env.staging] (and similar) blocks in wrangler.toml with different name, vars, or routes. Deploy to a specific environment:

npx wrangler deploy --env staging

Keep environment-specific secrets separate with the same secret put flow scoped to that env when needed.

Useful commands (cheat sheet)

| Command | Purpose | |--------|---------| | wrangler login | Authenticate CLI | | wrangler dev | Local development | | wrangler deploy | Deploy to Cloudflare | | wrangler tail | Stream live logs from a deployed Worker | | wrangler secret put NAME | Set a secret | | wrangler whoami | Confirm logged-in account |

Tips

1. Pin compatibility_date and bump it intentionally when you want new runtime behavior.
2. Use wrangler tail right after deploy to debug production issues.
3. CI/CD: run wrangler deploy in GitHub Actions (or similar) with a API token stored as CLOUDFLARE_API_TOKEN—Wrangler picks it up automatically.
4. For Pages + Functions, the workflow is related but not identical; this post focuses on standalone Workers.

Further reading

• Wrangler commands
• Workers bindings (KV, D1, R2, etc.)
• Migrate from Wrangler v3 to v4 if you’re upgrading an older project

With Wrangler installed, a small wrangler.toml, and wrangler dev / wrangler deploy, you have a fast loop from laptop to the edge.