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.

Both approaches below use 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.

Two approaches

1. Using varlock-wrangler - A thin wrapper for wrangler that injects env vars correctly, along with a one-line init import in your worker
2. With the Vite plugin - If you’re already using the Cloudflare Workers Vite plugin, you can add the varlock Cloudflare Vite plugin to automatically inject env vars and init code

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

   bun exec 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

   package.json

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

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 already using the Cloudflare Workers Vite plugin, varlockCloudflareVitePlugin is a thin wrapper that adds env var and varlock init code injection — no additional init import needed, and both ENV.MY_VAR and native env.MY_VAR work in dev and production.

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

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

   npm

   npm exec -- varlock init

   pnpm

   pnpm exec -- varlock init

   bun

   bun exec 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():

   varlockCloudflareVitePlugin({
     persistState: true,
     inspectorPort: 9229,
   })

4. Update your deploy script to use varlock-wrangler

   package.json

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

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 following commands:

varlock-wrangler dev

Wraps wrangler dev with automatic env injection:

1. Resolves your environment variables
2. Injects them into miniflare
3. Watches your .env files and restarts wrangler automatically when they change

varlock-wrangler deploy / versions upload

1. Resolves your environment variables using your .env.schema and .env files
2. Uploads non-sensitive values as Cloudflare vars (--var flags)
3. Uploads sensitive values as Cloudflare secrets (--secrets-file)
4. 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 are not 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. This ensures your env.MY_VAR access is properly typed alongside other Cloudflare bindings (KV, D1, etc.).

varlock-wrangler types

Other commands

All other wrangler commands (e.g., tail, secret list) are passed through to wrangler unchanged. You can use varlock-wrangler all the time, or just continue to use wrangler except for the commands listed above.

---

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.

If you are using Cloudflare’s CI, you can use the current branch name (WORKERS_CI_BRANCH) to determine the environment:

.env.schema

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

For more information, see the environments guide.