Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Workers

Wrangler: Create, Test and Deploy a Cloudflare Worker

Create a Worker project with Wrangler, read the wrangler config, run it locally, set secrets and variables, use environments, add routes and a cron trigger, and deploy.

Wrangler is Cloudflare's command-line tool for Workers. It scaffolds a project, runs your Worker locally, creates storage, uploads secrets and deploys. Everything is driven by one configuration file, so the same project builds the same way on your laptop and in CI.

The Worker platform cannot run here, so the commands below are read-only. Run them in your own terminal. The final example is a runnable checker that mimics what Wrangler validates in the config.

Create a project

You need Node.js and a Cloudflare account (the free plan is enough).

Terminal
npm create cloudflare@latest my-worker   # asks for a template (Hello World, etc.)
cd my-worker
npx wrangler login                       # opens a browser to authorize the CLI

The generator creates src/index.ts (or .js), a package.json and a Wrangler config file. Wrangler is installed as a project dependency, so npx wrangler ... uses the version your project pins.

The configuration file

Current Wrangler versions create wrangler.jsonc (older projects use wrangler.toml; both mean the same). A typical file:

JSONC
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-15",
  "compatibility_flags": ["nodejs_compat"],

  "vars": { "ENVIRONMENT": "production" },

  "kv_namespaces": [{ "binding": "CACHE", "id": "<namespace id>" }],
  "r2_buckets":    [{ "binding": "UPLOADS", "bucket_name": "my-uploads" }],
  "d1_databases":  [{ "binding": "DB", "database_name": "app-db", "database_id": "<id>" }],

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

The important fields:

Field Meaning
name The Worker's name; part of its *.workers.dev URL.
main Entry file Wrangler bundles.
compatibility_date Pins runtime behavior to a date, so a platform update never changes your Worker's semantics until you move the date.
compatibility_flags Opt-in features, such as nodejs_compat for Node.js built-in modules.
vars Plain (non-secret) variables, available as env.NAME.
bindings kv_namespaces, r2_buckets, d1_databases and more: how code reaches storage.
routes / custom_domains Which hostnames and paths invoke the Worker.
triggers.crons Scheduled invocations (the scheduled handler).

The dev loop

Terminal
npx wrangler dev          # local server, usually http://localhost:8787, live reload
npx wrangler dev --remote # run on Cloudflare's network against real remote resources
npx wrangler tail         # stream live logs and exceptions from the deployed Worker
npx wrangler deploy       # build, upload, and publish
npx wrangler versions list
npx wrangler rollback     # return to an earlier version

wrangler dev runs your code in a local simulator of the runtime and emulates KV, R2 and D1 on disk, so you can develop without touching production data. Use --remote only when you need the real thing.

Secrets and variables

Anything sensitive (API keys, signing secrets) must not go into vars, because that file is committed to Git. Use secrets instead:

Terminal
npx wrangler secret put STRIPE_KEY       # prompts for the value, stores it encrypted
npx wrangler secret list

For local development put the same names in a .dev.vars file (listed in .gitignore):

TEXT
STRIPE_KEY=sk_test_local_only

Both are read in code as env.STRIPE_KEY.

Environments

You usually want a staging copy. Wrangler supports named environments inside one config:

JSONC
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-15",
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": { "ENVIRONMENT": "staging" },
      "kv_namespaces": [{ "binding": "CACHE", "id": "<staging namespace id>" }]
    }
  }
}

Run npx wrangler deploy --env staging. Bindings and vars are not inherited by an environment; repeat everything the Worker needs, or it will start with missing bindings.

Scheduled and queue handlers

A Worker can export more than fetch:

JavaScript
export default {
  async fetch(request, env, ctx) { /* HTTP */ },
  async scheduled(controller, env, ctx) { /* cron: controller.cron, controller.scheduledTime */ },
};

Test the cron handler locally with npx wrangler dev --test-scheduled and then request http://localhost:8787/__scheduled?cron=0+*+*+*+*.

Deploy in CI

Create an API token in the dashboard (My Profile, API Tokens) with only the permissions the pipeline needs, store it as a CI secret named CLOUDFLARE_API_TOKEN and add CLOUDFLARE_ACCOUNT_ID. The pipeline step is then npx wrangler deploy. Never commit the token.

A config checker

Wrangler validates your config and warns about common mistakes. This stand-in reproduces a few such checks on a JSON object, so you can see the kinds of problems it catches.

JS Check a Wrangler-style config

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A release checklist

JS Deploy readiness checklist

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does compatibility_date do?

    Cloudflare changes runtime behavior only behind compatibility dates and flags, so existing Workers keep working until you opt in by moving the date.
  2. 2. Where should an API key for a third-party service live?

    vars are committed and visible. Secrets are stored encrypted and arrive through env without appearing in source.
  3. 3. You add an env.staging block and deploy it. Why might KV calls fail with 'undefined'?

    Environment blocks start empty for bindings and vars. Repeat every binding the Worker uses.
  4. 4. Which command streams live logs from a deployed Worker?

    wrangler tail shows console output and exceptions from the deployed Worker in real time.

Summary

  • Wrangler scaffolds (npm create cloudflare@latest), runs locally (wrangler dev), tails logs and deploys (wrangler deploy).
  • One config file (wrangler.jsonc or wrangler.toml) holds the name, entry file, compatibility date, variables, bindings, routes and cron triggers.
  • Put secrets in wrangler secret put and .dev.vars, never in vars.
  • Environments do not inherit bindings; repeat what you need.
  • CI deploys with a narrowly scoped API token stored as a secret.

Next: Choosing Between KV, R2, D1 and Durable Objects