|
| 1 | +--- |
| 2 | +title: Cloudflare Workers |
| 3 | +description: How to integrate varlock with Cloudflare Workers and Wrangler for secure, type-safe environment management |
| 4 | +--- |
| 5 | +import SyncedCodeTabs from '@/components/SyncedCodeTabs.astro' |
| 6 | +import { TabItem, Tabs, Steps } from "@astrojs/starlight/components"; |
| 7 | +import Badge from '@/components/Badge.astro'; |
| 8 | +import ExecCommandWidget from '@/components/ExecCommandWidget.astro'; |
| 9 | +import InstallJsDepsWidget from '@/components/InstallJsDepsWidget.astro'; |
| 10 | + |
| 11 | +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. |
| 12 | + |
| 13 | +## Two approaches |
| 14 | + |
| 15 | +There are two main ways to use varlock with Cloudflare Workers: |
| 16 | + |
| 17 | +1. **With Vite plugin** (recommended) - Use the [Varlock Vite integration](/integrations/vite/) alongside the [Cloudflare Workers Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/) |
| 18 | +2. **Without Vite** - Use Wrangler's `vars` and `secrets` directly |
| 19 | + |
| 20 | +## Approach 1: Using the Vite plugin (recommended) |
| 21 | + |
| 22 | +Using the [Cloudflare Workers Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/) allows more flexiblity in the bundling process. We can then use the [Varlock Vite plugin](/integrations/vite/) to bundle resolved environment variables into your built code, making it safe and straightforward to use. |
| 23 | + |
| 24 | +Even though it may feel a bit strange to use Vite on a backend-only project, it is the [recommended approach](https://developers.cloudflare.com/workers/development-testing/wrangler-vs-vite/#when-to-use-the-cloudflare-vite-plugin) by Cloudflare when you need more flexibility in your build process. |
| 25 | + |
| 26 | +:::caution[Bundled secrets] |
| 27 | +**Using this method, your sensitive values will never be exposed to any client-side code.** |
| 28 | + |
| 29 | +However, within the Cloudflare dashboard, your team members can view the bundled source code, and you must be mindful of sending source maps to external services. |
| 30 | +::: |
| 31 | + |
| 32 | +### Setup |
| 33 | + |
| 34 | +<Steps> |
| 35 | + |
| 36 | +1. **Install varlock and the Vite integration package** |
| 37 | + <InstallJsDepsWidget packages="@varlock/vite-integration varlock" /> |
| 38 | + |
| 39 | +1. **Run `varlock init` to set up your `.env.schema` file** |
| 40 | + |
| 41 | + This will guide you through setting up your `.env.schema` file, based on your existing `.env` file(s). Make sure to review it carefully. |
| 42 | + |
| 43 | + <ExecCommandWidget command="varlock init" showBinary={false} /> |
| 44 | + |
| 45 | +1. **Enable the Vite config plugin** |
| 46 | + |
| 47 | + Add the Varlock Vite plugin alongside the Cloudflare Workers Vite plugin to your `vite.config.*` file: |
| 48 | + |
| 49 | + ```diff lang="ts" title="vite.config.ts" |
| 50 | + import { defineConfig } from 'vite'; |
| 51 | + +import { varlockVitePlugin } from '@varlock/vite-integration'; |
| 52 | + |
| 53 | + export default defineConfig({ |
| 54 | + plugins: [ |
| 55 | + + varlockVitePlugin(), |
| 56 | + cloudflare(), |
| 57 | + // other plugins ... |
| 58 | + ], |
| 59 | + }); |
| 60 | + ``` |
| 61 | + |
| 62 | + 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. |
| 63 | + |
| 64 | +</Steps> |
| 65 | + |
| 66 | +### Update package.json scripts |
| 67 | + |
| 68 | +If you were not already using the Vite plugin, you'll also need to update your `package.json` scripts: |
| 69 | + |
| 70 | +```diff lang="json" title="package.json" |
| 71 | +{ |
| 72 | + "scripts": { |
| 73 | + "dev": "vite dev", |
| 74 | + "build": "vite build", |
| 75 | + "preview": "npm run build && vite preview", |
| 76 | + "deploy": "npm run build && wrangler deploy" |
| 77 | + } |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +You can see more details in the [Cloudflare's Vite getting started guide](https://developers.cloudflare.com/workers/vite-plugin/get-started/). |
| 82 | + |
| 83 | + |
| 84 | +---- |
| 85 | + |
| 86 | +## Approach 2: Using Wrangler vars and secrets (without Vite) |
| 87 | + |
| 88 | +For local development, you can use Wrangler's `--var` flag to pass the entire resolved env: |
| 89 | + |
| 90 | +```diff lang="json" title="package.json" |
| 91 | +{ |
| 92 | + "scripts": { |
| 93 | +- "dev": "wrangler dev", |
| 94 | ++ "dev": "wrangler dev --var \"__VARLOCK_ENV:$(varlock load --format json-full)\"", |
| 95 | + } |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +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). |
| 100 | + |
| 101 | +```diff lang="json" title="package.json" |
| 102 | +{ |
| 103 | + "scripts": { |
| 104 | +- "deploy": "wrangler deploy", |
| 105 | ++ "deploy": "wrangler deploy --var \"__VARLOCK_ENV:$(varlock load --format json-full)\"", |
| 106 | + } |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +:::caution[Team visibility] |
| 111 | +For deployments, when using `--var`, the environment variables will be visible in the Cloudflare dashboard to your team members. For higher security, consider using the secrets approach below. |
| 112 | +::: |
| 113 | + |
| 114 | +### Using Cloudflare secrets |
| 115 | + |
| 116 | +To attach the resolved env blob as a secret, you must use a 3-step deployment process using Wrangler's [versions commands](https://developers.cloudflare.com/workers/wrangler/commands/#versions): |
| 117 | + |
| 118 | +1. Upload new deployment version of your bundled code |
| 119 | +2. Create a second version with the secret attached |
| 120 | +3. Promote the latest version to be the active deployment |
| 121 | + |
| 122 | +```bash |
| 123 | +# Step 1: Create a version that's not deployed immediately |
| 124 | +# note the empty __VARLOCK_ENV so it will not reuse existing config |
| 125 | +npx wrangler versions upload --var "__VARLOCK_ENV:{}" |
| 126 | + |
| 127 | +# Step 2: Attach a new secret containing the resolved env as a single JSON object |
| 128 | +echo "$(APP_ENV=prod npx varlock load --format json-full)" | npx wrangler versions secret put __VARLOCK_ENV |
| 129 | + |
| 130 | +# Step 3: Activate the deployment |
| 131 | +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 |
| 132 | +``` |
| 133 | + |
| 134 | +:::tip[Future improvement] |
| 135 | +Cloudflare is working on the ability to push secrets atomically with the deploy command. See [this pull request](https://github.com/cloudflare/workers-sdk/pull/10896) for updates. Feel free to comment and tell them it is important! |
| 136 | +::: |
| 137 | + |
| 138 | +## Accessing environment variables |
| 139 | + |
| 140 | +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: |
| 141 | + |
| 142 | +```ts title="src/index.ts" |
| 143 | +// ❌ Do not use Cloudflare's built-in env |
| 144 | +import { env } from "cloudflare:workers"; |
| 145 | +console.log(env.API_KEY); |
| 146 | + |
| 147 | +// ✅ Recommended - uses varlock's ENV |
| 148 | +import { ENV } from 'varlock/env'; |
| 149 | +console.log(ENV.API_KEY); |
| 150 | +``` |
| 151 | + |
| 152 | +--- |
| 153 | + |
| 154 | +## Managing Multiple Environments |
| 155 | + |
| 156 | +Varlock can load multiple _environment-specific_ `.env` files (e.g., `.env.development`, `.env.preview`, `.env.production`) by using the [`@currentEnv` root decorator](/reference/root-decorators/#currentenv). |
| 157 | + |
| 158 | +If you are using Cloudflare's CI, you can use the current branch name (`WORKERS_CI_BRANCH`) to determine the environment: |
| 159 | + |
| 160 | +```env-spec title=".env.schema" |
| 161 | +# @currentEnv=$APP_ENV |
| 162 | +# --- |
| 163 | +WORKERS_CI_BRANCH= |
| 164 | +# @type=enum(development, preview, production, test) |
| 165 | +APP_ENV=remap($WORKERS_CI_BRANCH, production="main", preview=regex(.*), development=undefined) |
| 166 | +``` |
| 167 | + |
| 168 | +For more information, see the [environments guide](/guides/environments). |
0 commit comments