Skip to main content

Wrangler CLI & Project Setup

Wrangler is the official command-line interface for developing Cloudflare Workers. It handles authenticating to your Cloudflare account, scaffolding new projects, running a local dev server, managing secrets, and deploying code.

Learning Focus

By the end of this module, you will understand how to initialize a Worker, run a completely local proxy-free development server, read production logs, and manage configuration via wrangler.toml.

Installation and Authentication​

Wrangler requires Node.js 16.13.0 or later. It is recommended to run Wrangler via npx so you always use the latest version tied to your project, but you can also install it globally.

Authenticate Setup​

Before creating a project, authenticate Wrangler with your Cloudflare account.

# Login via browser
npx wrangler login

# Verify your connection and check who you are logged in as
npx wrangler whoami

If you are running in an automated environment (like CI/CD), you can use an API token instead of the browser login:

export CLOUDFLARE_API_TOKEN="your_secure_token"

Creating a Project​

Scaffold a new Worker using the create-cloudflare CLI (often aliased to C3).

npm create cloudflare@latest my-first-worker

The prompt will ask you a series of questions:

  1. What type of application? (Select "Hello World" Worker)
  2. Do you want to use TypeScript? (Highly recommended: Select Yes)
  3. Do you want to deploy your application? (Select No for now)

Project Structure​

A standard generated Worker looks like this:

my-first-worker/
├── node_modules/
├── src/
│   └── index.ts        ← Your actual Worker code
├── package.json
├── package-lock.json
├── tsconfig.json
└── wrangler.toml       ← The core configuration file

Configuration: wrangler.toml​

Everything about your Worker's environment is defined in wrangler.toml. This allows you to treat your infrastructure as code (IaC).

wrangler.toml
# The name of your worker as it will appear in the Cloudflare Dashboard
name = "my-first-worker"

# The entrypoint file
main = "src/index.ts"

# The date to lock backward compatibility. Always set to current date.
compatibility_date = "2024-03-01"

# Automatically add node.js compatibility polyfills
compatibility_flags = ["nodejs_compat"]

# Define environment variables
[vars]
API_URL = "https://api.example.com"
ENVIRONMENT = "production"
Compatibility Dates

Cloudflare frequently updates the V8 runtime. The compatibility_date ensures that future updates don't break your existing code by locking your Worker to the API behavior as it existed on that date. Do not randomly change this in production without testing first.

Local Development (Miniflare)​

Wrangler uses a tool called Miniflare under the hood. Miniflare runs the actual open-source workerd runtime locally on your machine. This means your local environment operates exactly like the production edge environment.

# Start the local development server
npx wrangler dev

By default, this will run on http://localhost:8787.

The dev command features:​

  • Hot Reloading: Code changes instantly restart the Worker.
  • Local State: If your Worker uses KV or D1 databases, wrangler dev creates local SQLite files in a .wrangler/ folder so you can test without touching production data.
  • Remote Integration: You can pass --remote to wrangler dev to run your local code but access production KV/D1 data if needed.

Deployment​

Deploying pushes your code to Cloudflare's edge network globally. Typically this process takes less than 5 seconds.

npx wrangler deploy

Upon success, Wrangler will output your *.workers.dev subdomain URL.

Monitoring and Logging: wrangler tail​

Once deployed, how do you see console.log() outputs? You use wrangler tail.

tail connects to the Cloudflare edge and streams live logs from your Worker directly to your terminal.

# Stream all logs from production
npx wrangler tail

# Format the output as pure JSON for parsing with tools like `jq`
npx wrangler tail --format=json

# Only stream logs containing errors
npx wrangler tail --status=error
Sampling

If your Worker receives thousands of requests per second, wrangler tail will naturally sample the logs to prevent crashing your local terminal. Don't rely on tail for long-term logging (use Logpush for that).

Secret Management​

Environment variables in your wrangler.toml are visible in plain text. For API keys or passwords, you must use Secrets.

# Set a secret variable
npx wrangler secret put STRIPE_API_KEY
# (The CLI will securely prompt you to type the key)

# Delete a secret
npx wrangler secret delete STRIPE_API_KEY

For local development, secrets shouldn't match production. Instead, create a .dev.vars file in the root of your project:

.dev.vars
STRIPE_API_KEY="sk_test_12345"

Note: Ensure .dev.vars is added to your .gitignore!

Conclusion​

You are now authenticated, your project is set up, and you know how to run, deploy, and monitor your code.

Next, we'll dive into how to actually write the code that responds to HTTP traffic. Proceed to Module 3: Routing and Triggers.