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 handling.

There are two main ways to use varlock with Cloudflare Workers:

1. With Vite plugin (recommended) - Use the Varlock Vite integration alongside the Cloudflare Workers Vite plugin
2. Without Vite - Use Wrangler’s vars and secrets directly

Using the Cloudflare Workers Vite plugin allows more flexiblity in the bundling process. We can then use the Varlock Vite plugin to bundle resolved environment variables into your built code, making it safe and straightforward to use.

Even though it may feel a bit strange to use Vite on a backend-only project, it is the recommended approach by Cloudflare when you need more flexibility in your build process.

1. Install varlock and the Vite integration package

   • npm
   • yarn
   • pnpm
   • vlt
   • bun

   npm install @varlock/vite-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
   • yarn
   • pnpm
   • vlt
   • bun

   npm exec -- varlock init

3. Enable the Vite config plugin

   Add the Varlock Vite plugin alongside the Cloudflare Workers Vite plugin to your vite.config.* file:

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

   The varlock plugin will automatically detect Cloudflare Workers and use the resolved-env mode, which injects the fully resolved environment data into your built code.

If you were not already using the Vite plugin, you’ll also need to update your package.json scripts:

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

You can see more details in the Cloudflare’s Vite getting started guide.

For local development, you can use Wrangler’s --var flag to pass the entire resolved env:

{
  "scripts": {
    "dev": "wrangler dev",
    "dev": "wrangler dev --var \"__VARLOCK_ENV:$(varlock load --format json-full)\"",
  }
}

For deployments we can use the same method. Note that you may need to set your current env, either within the deploy command or infer it from the CI environemnt (see below).

{
  "scripts": {
    "deploy": "wrangler deploy",
    "deploy": "wrangler deploy --var \"__VARLOCK_ENV:$(varlock load --format json-full)\"",
  }
}

To attach the resolved env blob as a secret, you must use a 3-step deployment process using Wrangler’s versions commands:

1. Upload new deployment version of your bundled code
2. Create a second version with the secret attached
3. Promote the latest version to be the active deployment

# Step 1: Create a version that's not deployed immediately
# note the empty __VARLOCK_ENV so it will not reuse existing config
npx wrangler versions upload --var "__VARLOCK_ENV:{}"

# Step 2: Attach a new secret containing the resolved env as a single JSON object
echo "$(APP_ENV=prod npx varlock load --format json-full)" | npx wrangler versions secret put __VARLOCK_ENV

# Step 3: Activate the deployment
npx wrangler versions deploy --version-id=$(npx wrangler versions list | grep -oE 'Version ID:[[:space:]]*[a-f0-9-]+' | tail -n1 | sed 's/Version ID:[[:space:]]*//') --percentage=100 --yes

Because we are not re-emitting all env vars into the Cloudflare’s vars/secrets, you must using varlock’s ENV object instead of Cloudflare’s built-in environment variable access:

// ❌ Do not use Cloudflare's built-in env
import { env } from "cloudflare:workers";
console.log(env.API_KEY);

// ✅ Recommended - uses varlock's ENV
import { ENV } from 'varlock/env';
console.log(ENV.API_KEY);

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:

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

For more information, see the environments guide.