Skip to main content

​
Prerequisites

Before installing the Workers SDK, ensure your system meets these requirements:

Node.js

Required: Node.js 20.0.0 or higherCheck your version: node --version

Package Manager

npm, pnpm, or yarnRecommended: pnpm for faster installs

​
Operating System Support

Wrangler is supported on:
  • macOS: 13.5 or later
  • Windows: Windows 11
  • Linux: Distributions with glibc 2.35 or later
This follows the workerd OS support policy.

​
Installation Methods

There are several ways to install and use the Workers SDK depending on your workflow. The fastest way to get started is using Create Cloudflare (C3), which scaffolds a complete project:
1

Run the create command

npm create cloudflare@latest
This installs the latest version of create-cloudflare and runs the interactive setup wizard.
2

Follow the prompts

C3 will guide you through:
  • Project name and directory
  • Template selection (Hello World, frameworks, etc.)
  • TypeScript or JavaScript
  • Git initialization
  • Deployment option
3

Start developing

cd your-project-name
npm run dev
C3 automatically installs Wrangler and all necessary dependencies for your chosen template.

​
Method 2: Install Wrangler Globally

Install Wrangler globally to use it across multiple projects: 
npm install -g wrangler
Verify the installation: 
wrangler --version
# wrangler 4.69.0
Global installations may conflict with project-specific versions. Consider using npx or project-local installations for better version control.

​
Method 3: Install as Project Dependency

Add Wrangler to an existing project:
1

Install Wrangler

npm install wrangler --save-dev
2

Add scripts to package.json

package.json
{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "tail": "wrangler tail"
  },
  "devDependencies": {
    "wrangler": "^4.69.0"
  }
}
3

Run with npm scripts

npm run dev

​
Method 4: Use npx (No Installation)

Run Wrangler commands without installing: 
npx wrangler@latest dev
npx wrangler@latest deploy
npx downloads and runs the latest version each time. This ensures you always have the newest version but may be slower.

​
Installing Additional Packages

Depending on your use case, you may want to install additional Workers SDK packages:

​
Miniflare (Local Development Runtime)

Miniflare is included with Wrangler but can be used standalone: 
npm install miniflare --save-dev
Current version: 4.20260305.0 
import { Miniflare } from "miniflare";

const mf = new Miniflare({
  script: `export default {
    async fetch(request, env, ctx) {
      return new Response("Hello Miniflare!");
    }
  }`,
});

const response = await mf.dispatchFetch("http://localhost:8787/");
console.log(await response.text());

​
Workers Types (TypeScript Support)

Add TypeScript definitions for the Workers runtime: 
npm install @cloudflare/workers-types --save-dev
Then configure tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "lib": ["ES2022"],
    "types": ["@cloudflare/workers-types"]
  }
}

​
Vitest Pool Workers (Testing)

For testing Workers with Vitest in the actual runtime: 
npm install @cloudflare/vitest-pool-workers --save-dev
Configure vitest.config.js:
vitest.config.js
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.jsonc" },
      },
    },
  },
});

​
Configuration

After installation, configure your Worker with a wrangler.jsonc, wrangler.json, or wrangler.toml file: 
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "./src/index.ts",
  "compatibility_date": "2026-03-03",
  // Add your bindings here
  "vars": {
    "ENVIRONMENT": "production"
  }
}
Use wrangler.jsonc for better editor support with comments and the $schema field for autocomplete.

​
Authentication

Before deploying Workers, authenticate with Cloudflare:
1

Log in to Cloudflare

wrangler login
This opens a browser window to authorize Wrangler.
2

Verify authentication

wrangler whoami
You should see your account email and account ID.
For CI/CD environments, use API tokens instead:
  1. Create an API token at dash.cloudflare.com/profile/api-tokens
  2. Use the “Edit Cloudflare Workers” template
  3. Set the CLOUDFLARE_API_TOKEN environment variable:
export CLOUDFLARE_API_TOKEN=your-api-token
Legacy authentication (not recommended):
export CLOUDFLARE_ACCOUNT_ID=your-account-id
export CLOUDFLARE_API_KEY=your-api-key
export CLOUDFLARE_EMAIL=your-email

​
Version Management

​
Checking Versions

Check installed package versions: 
# Wrangler version
wrangler --version

# All package versions in your project
npm list wrangler miniflare @cloudflare/workers-types

​
Updating Packages

Keep your Workers SDK packages up to date: 
npm update wrangler
To upgrade to the latest version: 
npm install wrangler@latest

​
Beta Releases

Beta releases are updated frequently and not suitable for production. Use only for testing unreleased features.
Install beta releases from the main branch: 
npm install https://pkg.pr.new/wrangler@main
Available beta packages:
  • wrangler@main
  • create-cloudflare@main
  • miniflare@main
  • @cloudflare/vitest-pool-workers@main

​
Workspace Setup (Monorepo)

For monorepo setups using pnpm workspaces:
pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'
Install Wrangler at the workspace root: 
pnpm add -Dw wrangler
Each package can have its own wrangler.jsonc configuration.

​
Troubleshooting

Error: This version of Wrangler requires at least Node.js v20.0.0Solution: Update Node.js using nvm or download from nodejs.org
nvm install 20
nvm use 20
Permission errors when installing globally:Solution: Use a Node version manager (nvm) or install in a project directory instead of globally.
Cannot find module wrangler:Solution: Ensure you’re in the correct directory and dependencies are installed:
npm install
Windows: Make sure you’re using Windows 11. Windows 10 is not supported.Linux: Verify glibc version:
ldd --version
You need glibc 2.35 or higher.

​
Next Steps

Now that you have the Workers SDK installed:

Create Your First Worker

Follow the quickstart guide to build and deploy

Configure Your Worker

Learn about configuration options

Set Up Testing

Configure Vitest for Workers testing
For detailed documentation on all configuration options, see the official Wrangler documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us