Cloudflare Workers

Varlock provides a robust solution for managing environment variables in Cloudflare Workers, offering validation, type safety, and security features that go beyond Cloudflare’s built-in environment variable and secrets handling.

Our integration relies on using varlock-wrangler — a thin wrapper around wrangler that automatically resolves and uploads your env vars as Cloudflare secrets and vars during deployment, and injects them into miniflare during local dev.

Requires nodejs_compat

Varlock relies on a handful of node:* built-ins at runtime, so your worker must opt into Cloudflare’s Node.js compatibility layer. Add nodejs_compat to your compatibility_flags in wrangler.toml / wrangler.json — without it, the worker will fail to start with “Cannot resolve ‘node:…’” errors.

wrangler.json

{
  "compatibility_flags": ["nodejs_compat"]
}

Choosing an approach

All paths use the same .env.schema and varlock-wrangler deploy for production uploads — the difference is how env reaches your worker during local dev and build:

Approach	Best when	Dev / build
varlock-wrangler	Plain Workers, minimal tooling	varlock-wrangler dev injects env via FIFO and watches .env files; varlock-wrangler deploy uploads vars + secrets
Vite plugin	Already using @cloudflare/vite-plugin	vite dev injects into miniflare automatically; vite build + varlock-wrangler deploy
SvelteKit adapter plugin	SvelteKit with @sveltejs/adapter-cloudflare	vite dev via an SSR entry loader; vite build + varlock-wrangler deploy

SvelteKit uses a separate entry point

@cloudflare/vite-plugin does not support SvelteKit (workers-sdk#8922). SvelteKit projects must use varlockSvelteKitCloudflarePlugin from @varlock/cloudflare-integration/sveltekit — not the standard Vite plugin.

Approach 1: Using varlock-wrangler

Replace your wrangler commands with varlock-wrangler and initialize varlock in your worker code with a single import. It’s a thin wrapper that wires up your env vars correctly, and passes everything else through unchanged.

Setup

1. Install packages

   npm

   npm install @varlock/cloudflare-integration varlock

   pnpm

   pnpm add @varlock/cloudflare-integration varlock

   bun

   bun add @varlock/cloudflare-integration varlock

   yarn

   yarn add @varlock/cloudflare-integration varlock

   vlt

   vlt install @varlock/cloudflare-integration varlock

2. Run varlock init to set up your .env.schema file

   This will guide you through setting up your .env.schema file, based on your existing .env file(s). Make sure to review it carefully.

   npm

   npm exec -- varlock init

   pnpm

   pnpm exec -- varlock init

   bun

   bunx varlock init

   vlt

   vlx -- varlock init

   yarn

   yarn exec -- varlock init

3. Add the varlock init import to your worker entry point

   This initializes varlock’s ENV proxy and applies console redaction and response leak detection (unless disabled):

   src/index.ts

   import '@varlock/cloudflare-integration/init';
   import { ENV } from 'varlock/env';
   
   export default {
     async fetch(request, env, ctx) {
       // both work:
       console.log(ENV.MY_VAR);  // varlock (recommended)
       console.log(env.MY_VAR);  // native Cloudflare
       return new Response('Hello!');
     },
   };

4. Update your package.json scripts to use varlock-wrangler

   Use varlock-wrangler as a drop-in replacement for wrangler:

   package.json

   {
     "scripts": {
       "dev": "varlock-wrangler dev",
       "deploy": "varlock-wrangler deploy",
       "types": "varlock-wrangler types",
     }
   }

   If you deploy via Cloudflare Workers Builds instead of a local/CI script, override the deploy command in your Cloudflare dashboard under Settings → Build → Deploy command — see Workers Builds below.

How it works

• In dev: varlock-wrangler dev resolves your env and injects it into wrangler using --env-file with a named pipe (unix/mac) or temp file (windows). It also watches your .env files and automatically restarts wrangler when they change - something wrangler dev doesn’t do.
• In production: varlock-wrangler deploy (and varlock-wrangler versions upload) attaches non-sensitive values as Cloudflare vars (via --var) and sensitive values as Cloudflare secrets via --secrets-file. The worker reads them at runtime via import { env } from 'cloudflare:workers'.

---

Approach 2: With the Vite plugin

If you’re building with Vite, varlockCloudflareVitePlugin wraps the Cloudflare Workers Vite plugin and adds env var + varlock init injection — no extra init import needed, and both ENV.MY_VAR and native env.MY_VAR work in dev and production.

For SvelteKit on Cloudflare, use the dedicated varlockSvelteKitCloudflarePlugin from @varlock/cloudflare-integration/sveltekit instead.

Setup

1. Install packages

   npm

   npm install @varlock/cloudflare-integration @cloudflare/vite-plugin varlock

   pnpm

   pnpm add @varlock/cloudflare-integration @cloudflare/vite-plugin varlock

   bun

   bun add @varlock/cloudflare-integration @cloudflare/vite-plugin varlock

   yarn

   yarn add @varlock/cloudflare-integration @cloudflare/vite-plugin varlock

   vlt

   vlt install @varlock/cloudflare-integration @cloudflare/vite-plugin varlock

   @cloudflare/vite-plugin is an (optional) peer dependency — this plugin wraps it, so you need it installed in the same project. SvelteKit users should omit it (see the SvelteKit callout at the top of this page).

2. Run varlock init to set up your .env.schema file

   npm

   npm exec -- varlock init

   pnpm

   pnpm exec -- varlock init

   bun

   bunx varlock init

   vlt

   vlx -- varlock init

   yarn

   yarn exec -- varlock init

3. Update your Vite config

   Replace the cloudflare() plugin with varlockCloudflareVitePlugin() — it is a thin wrapper of the Cloudflare vite plugin and passes through all config:

   vite.config.ts

   import { defineConfig } from 'vite';
   import { cloudflare } from '@cloudflare/vite-plugin';
   import { varlockCloudflareVitePlugin } from '@varlock/cloudflare-integration';
   
   export default defineConfig({
     plugins: [
       cloudflare(),
       varlockCloudflareVitePlugin(),
       // other plugins ...
     ],
   });

   Any options you were passing to cloudflare() can be passed directly to varlockCloudflareVitePlugin() at the top level.

4. Deploy with varlock-wrangler

   Use varlock-wrangler deploy instead of wrangler deploy in your deploy script:

   package.json

   {
     "scripts": {
       "dev": "vite dev",
       "build": "vite build",
       "deploy": "npm run build && varlock-wrangler deploy"
     }
   }

   If you deploy via Cloudflare Workers Builds instead of a local/CI script, override the deploy command in your Cloudflare dashboard under Settings → Build → Deploy command — see Workers Builds below.

Remove .dev.vars

If you have a .dev.vars file in your project root, delete it. Varlock manages env injection automatically — a .dev.vars file will conflict and the plugin will throw an error. This also applies to .dev.vars.<environment> files.

How it works

• In dev: Resolved vars are automatically injected into miniflare’s bindings.
• In production: Non-sensitive values are statically replaced at build time by vite. varlock-wrangler deploy sets non-sensitive values as Cloudflare vars and sensitive values as secrets.

Upgrading from @varlock/vite-integration

If you were previously using varlockVitePlugin() from @varlock/vite-integration with Cloudflare Workers:

1. Install @varlock/cloudflare-integration (you can remove @varlock/vite-integration — it’s included)
2. In vite.config.ts, replace both varlockVitePlugin() and cloudflare() with varlockCloudflareVitePlugin()
3. Replace wrangler deploy with varlock-wrangler deploy in your deploy script

vite.config.ts

import { varlockVitePlugin } from '@varlock/vite-integration';
import { cloudflare } from '@cloudflare/vite-plugin';
import { varlockCloudflareVitePlugin } from '@varlock/cloudflare-integration';

export default defineConfig({
  plugins: [
    varlockVitePlugin(),
    cloudflare(),
    varlockCloudflareVitePlugin(),
  ],
});

Your secrets will no longer be bundled into the JS artifact — they’ll be stored in Cloudflare’s secret management instead.

---

varlock-wrangler CLI

varlock-wrangler is a thin wrapper around wrangler. It enhances the commands below; everything else (tail, secret list, etc.) is passed through unchanged, so you can use varlock-wrangler everywhere or just for these commands.

varlock-wrangler dev

Wraps wrangler dev with automatic env injection. Resolves your environment variables, injects them into miniflare, and watches your .env files to restart wrangler when they change.

varlock-wrangler deploy / versions upload

Resolves your environment variables from .env.schema + .env files, then uploads non-sensitive values as Cloudflare vars (--var), sensitive values as Cloudflare secrets (--secrets-file), and includes a __VARLOCK_ENV secret containing the full resolved env graph for the varlock runtime.

Secure secret handling

On Unix, secrets are passed to wrangler commands via a named pipe (FIFO) and never written to disk. On Windows, a temporary file is used and immediately deleted after the deploy completes.

Varlock owns your env vars

varlock-wrangler deploy replaces all Cloudflare vars and secrets with the ones defined in your .env.schema. Any vars or secrets set manually via the Cloudflare dashboard or wrangler secret put that aren’t in your schema will be removed on the next deploy. If you need additional bindings (KV, D1, etc.), configure them in your wrangler.toml as usual — only plain vars/secrets are affected.

varlock-wrangler types

Generates Cloudflare Worker types (the Env interface) including all varlock-managed environment variables, so your env.MY_VAR access is properly typed alongside other Cloudflare bindings (KV, D1, etc.).

---

Log redaction and leak prevention

Both integration approaches automatically enable log redaction (sensitive values are masked in console output) and response leak detection (responses are scanned for accidentally exposed secrets). These are enabled by default and can be disabled in your .env.schema using root decorators:

.env.schema

# @redactLogs=false
# @preventLeaks=false

For more details, see the root decorators reference.

---

Managing Multiple Environments

Varlock can load multiple environment-specific .env files (e.g., .env.development, .env.preview, .env.production) by using the @currentEnv root decorator.

The simplest approach is to use the built-in VARLOCK_ENV variable, which auto-detects the deployment environment on most CI platforms — including Cloudflare Workers Builds (via WORKERS_CI_BRANCH), Vercel, Netlify, and others. Locally it resolves to development, and during tests to test.

.env.schema

# @currentEnv=$VARLOCK_ENV
# ---

If you need more control — for example mapping specific branches to specific environments — you can define your own env-selection var instead:

.env.schema

# @currentEnv=$APP_ENV
# ---
WORKERS_CI_BRANCH=
# @type=enum(development, preview, production, test)
APP_ENV=remap($WORKERS_CI_BRANCH, "main", production, /.*/, preview, undefined, development)

For more information, see the environments guide.

---

Cloudflare Workers Builds (CI/CD)

If you deploy via Cloudflare Workers Builds, two pieces of setup are required in the dashboard — neither can be configured from a file in the repo:

1. Override the Deploy command

   Under Settings → Build → Deploy command, replace the default npx wrangler deploy with:

   npx varlock-wrangler deploy

   Without this override, Cloudflare runs stock wrangler deploy, which skips varlock’s env resolution and leaves your worker without its resolved vars/secrets at runtime.

2. Set any secret-zero vars under Build variables

   Any env vars that varlock itself needs during load — for example a 1Password service account token, a GCP key — must be set under Settings → Build → Variables and Secrets. These are made available to the build step, where varlock-wrangler deploy resolves your full env graph and uploads the result to the worker runtime as regular vars/secrets.

   Vars that only your worker needs at runtime (not varlock itself) don’t need to be set here — they’ll be resolved by varlock and set automatically by varlock-wrangler deploy.

---

Deploying from your own CI

Deploying from your own CI (GitHub Actions, GitLab CI, a self-hosted runner) instead of Cloudflare Workers Builds works the same way — and isn’t really Cloudflare-specific. The same secret-zero rule applies: any var varlock needs to resolve your secrets (a 1Password service account token, a GCP key, etc.) must be present in the job environment before varlock-wrangler deploy runs.

.github/workflows/deploy-worker.yml

jobs:
  deploy:
    permissions:
      id-token: write   # required for OIDC-backed plugins
      contents: read
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - run: npx varlock-wrangler deploy
        env:
          # Only vars varlock needs to *resolve* secrets — not every worker var
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}

For supported providers, varlock can authenticate with short-lived OIDC tokens from your CI instead of long-lived keys — see the OIDC workload identity guide. Run varlock load in an earlier step to fail fast on schema errors without exposing values.

---

Multi-worker and auxiliary Workers

Cloudflare supports running multiple Workers in one dev session — a primary Worker plus auxiliary Workers reachable via service bindings. The Vite plugin exposes this through auxiliaryWorkers in vite.config.ts.

Single-worker env injection today

Varlock currently resolves and uploads env vars for one Wrangler config per deploy. varlock-wrangler deploy injects vars/secrets into the worker named by the target wrangler.toml / wrangler.json — it does not automatically propagate env to auxiliary Workers or sibling configs passed to wrangler dev -c ./a.json -c ./b.json.

For multi-worker repos today:

• Deploy each Worker separately with varlock-wrangler deploy -c <that-worker-config>, or
• Share a single .env.schema and run deploy once per worker script, or
• Use varlock run to inject resolved env when invoking a non-wrangler deploy tool (see non-wrangler deploy tools below).

First-class multi-worker / auxiliary-worker support is not implemented yet. If this blocks your setup, join Discord and share your wrangler layout and which Workers need which vars.

---

When things go wrong

Cannot resolve 'node:...' at worker startup

Your worker is missing the Node.js compatibility layer. Add nodejs_compat to compatibility_flags — see the nodejs_compat caution near the top of this page.

.dev.vars conflicts with the Vite plugin

Delete .dev.vars and .dev.vars.<environment> files when using the Vite plugin or varlock-wrangler dev. Varlock owns env injection; leftover Wrangler env files cause hard errors.

Vars or secrets missing after deploy

• Confirm you deploy with varlock-wrangler deploy, not stock wrangler deploy — especially on Workers Builds
• Check that secret-zero CI vars are set for any plugin-backed items varlock must resolve at deploy time
• Remember that varlock-wrangler deploy replaces all Cloudflare vars and secrets with schema-defined ones — manually added dashboard secrets not in your schema are removed

Non-wrangler deploy tools (Alchemy, SST, Pulumi)

If you deploy Workers with IaC tools other than wrangler — Alchemy, SST, Pulumi, Terraform, etc. — you can still use varlock for fail-fast validation and secret resolution via varlock run, which injects resolved values into process.env for the deploy tool to read.

What you cannot get today without varlock-wrangler: the in-worker runtime layer (@varlock/cloudflare-integration/init) that provides console redaction and response leak detection. That layer reads a __VARLOCK_ENV binding that only varlock-wrangler produces today.

A public API to build __VARLOCK_ENV bindings for non-wrangler deploy tools is planned but not available yet. Until then, teams on Alchemy/SST/Pulumi typically rely on varlock for validation + env injection at deploy time and skip the in-worker runtime protections.

---

Varlock vs Cloudflare’s built-in env management

Cloudflare Workers have built-in support for vars and secrets, but managing them across environments quickly becomes painful. Here’s what Varlock adds:

• Single source of truth — Instead of scattering config across the Cloudflare dashboard, wrangler.toml, .dev.vars, and your code, everything is defined in one .env.schema file that works across local dev, preview, and production.
• Validation before deploy — Cloudflare only has basic required var validation. Varlock catches missing vars, wrong types, and invalid values before your worker starts — not when it crashes at runtime.
• Pull secrets from vaults — Instead of manually running wrangler secret put or copy-pasting values in the dashboard, pull secrets directly from 1Password, AWS Secrets Manager, HashiCorp Vault, and more.
• Log redaction & leak prevention — Cloudflare doesn’t prevent you from accidentally console.log-ing a secret or including one in a response body. Varlock automatically redacts sensitive values in logs and scans outgoing responses for leaked secrets.
• Simpler multi-environment setup — Wrangler’s [env.staging] / [env.production] blocks duplicate config and don’t support .env file overrides. Varlock uses familiar .env.production / .env.preview files with a single schema, and auto-detects the current environment in CI.
• Local dev that matches production — .dev.vars is completely disconnected from your production secrets. With Varlock, local dev resolves from the same schema and same secret sources, so there’s no drift between environments.
• AI-safe by design — Your .env.schema gives AI coding tools full context on your config (names, types, descriptions) without ever exposing secret values.