Environment:Helicone Helicone Wrangler CLI
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Deployment |
| Last Updated | 2026-02-14 06:00 GMT |
Overview
Wrangler 4.27+ CLI tool for local development, testing, and deployment of Cloudflare Workers in the Helicone proxy layer.
Description
Wrangler is the Cloudflare Workers CLI that provides local development simulation (`wrangler dev`), deployment (`wrangler deploy`), and secret management (`wrangler secret`) for the Helicone worker proxy. It reads configuration from `wrangler.toml` and simulates the Workers runtime locally, including Durable Objects, KV namespaces, and Queues. The local development mode provides a Miniflare-based simulator that closely mimics the production Workers environment.
Usage
Use this environment for worker development and deployment. It is required for local proxy development (`wrangler dev --local`), running worker tests (`vitest` which uses Wrangler internals), and deploying to Cloudflare's edge network.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Node.js | >= 20 | Required to run Wrangler |
| CLI | Wrangler >= 4.27.0 | Installed as devDependency in worker package |
| Network | Internet access | For deployment; local dev works offline |
Dependencies
NPM Packages
- `wrangler` >= 4.27.0 (Cloudflare Workers CLI)
- `vitest` ~3.2.0 (test runner, integrates with Wrangler)
- `@cloudflare/vitest-pool-workers` (Workers-specific test pool)
Configuration Files
- `worker/wrangler.toml` (main configuration)
- `worker/vitest.config.mts` (test configuration)
Credentials
- `CLOUDFLARE_API_TOKEN`: API token for deployment (set via environment or `wrangler login`)
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare account identifier
Quick Install
# Install worker dependencies (includes Wrangler)
cd worker && yarn install
# Start local development
npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787
# Deploy to Cloudflare
npx wrangler deploy
Code Evidence
Wrangler dependency from `worker/package.json`:
"devDependencies": {
"wrangler": "^4.27.0",
"@cloudflare/vitest-pool-workers": "^0.8.34"
}
Local dev command pattern from `CLAUDE.md`:
cd worker && npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `wrangler: command not found` | Wrangler not installed | Run `yarn install` in the worker directory |
| `Error: No account id found` | Not authenticated | Run `wrangler login` or set `CLOUDFLARE_ACCOUNT_ID` |
| `Error: The compatibility date cannot be in the future` | `compatibility_date` ahead of Wrangler version | Update Wrangler or adjust compatibility_date in wrangler.toml |
Compatibility Notes
- Local vs Production: `wrangler dev --local` uses Miniflare to simulate the Workers runtime. Some edge cases (e.g., Durable Object persistence, geographic routing) behave differently locally.
- WORKER_TYPE variable: Must be passed via `--var` flag in local dev mode. Different worker types (OPENAI_PROXY, ANTHROPIC_PROXY, etc.) activate different proxy routers.