You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
16
12
17
-
18
-
## Two Approaches
13
+
## Two approaches
19
14
20
15
There are two main ways to use varlock with Cloudflare Workers:
21
16
22
-
1.**With Vite plugin** (recommended) - Use the Vite integration alongside the Cloudflare Workers Vite plugin
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/)
23
18
2.**Without Vite** - Use Wrangler's `vars` and `secrets` directly
24
19
25
-
## Approach 1: Using the Vite Plugin (Recommended)
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.
26
25
27
-
The Vite plugin bundles resolved environment variables into your built code, making it safe and straightforward to use.
26
+
:::caution[Bundled secrets]
27
+
**Using this method, your sensitive values will never be exposed to any client-side code.**
28
28
29
-
:::note[Backend-only Workers]
30
-
Even for backend-only Workers, using the Vite plugin is recommended. Because it bundles the resolved env into your built code, within the Cloudflare dashboard, your team members can view the source code. Be mindful of this when including sensitive values or sending source maps to external services.
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.
31
30
:::
32
31
33
32
### Setup
@@ -45,156 +44,118 @@ Even for backend-only Workers, using the Vite plugin is recommended. Because it
45
44
46
45
1.**Enable the Vite config plugin**
47
46
48
-
Add both the varlock Vite plugin and the Cloudflare Workers Vite plugin to your `vite.config.*` file:
47
+
Add the Varlock Vite plugin alongside the Cloudflare Workers Vite plugin to your `vite.config.*` file:
49
48
50
49
```diff lang="ts" title="vite.config.ts"
51
50
import { defineConfig } from 'vite';
52
51
+import { varlockVitePlugin } from '@varlock/vite-integration';
53
52
54
53
export default defineConfig({
55
-
- plugins: [otherPlugin()],
56
-
+ plugins: [
54
+
plugins: [
57
55
+ varlockVitePlugin(),
58
-
+ cloudflare(),
59
-
+otherPlugin()
60
-
+ ],
56
+
cloudflare(),
57
+
// other plugins ...
58
+
],
61
59
});
62
60
```
63
61
64
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.
65
63
66
64
</Steps>
67
65
68
-
### Local Development
66
+
### Update package.json scripts
69
67
70
-
For local development, you can use Wrangler's `--var` flag to pass the resolved environment variables:
68
+
If you were not already using the Vite plugin, you'll also need to update your `package.json` scripts:
71
69
72
70
```diff lang="json" title="package.json"
73
71
{
74
72
"scripts": {
75
-
- "dev": "wrangler dev",
76
-
+ "dev": "wrangler dev --var \"__VARLOCK_ENV:$(varlock load --format json-full)\"",
73
+
"dev": "vite dev",
74
+
"build": "vite build",
75
+
"preview": "npm run build && vite preview",
76
+
"deploy": "npm run build && wrangler deploy"
77
77
}
78
78
}
79
79
```
80
80
81
-
### Deployment
81
+
You can see more details in the [Cloudflare's Vite getting started guide](https://developers.cloudflare.com/workers/vite-plugin/get-started/).
82
+
82
83
83
-
For deployments, you can use the same approach with the `--var` flag:
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:
+ "dev": "wrangler dev --var \"__VARLOCK_ENV:$(varlock load --format json-full)\"",
90
95
}
91
96
}
92
97
```
93
98
94
-
:::caution[Team visibility]
95
-
When using `--var`, the environment variables will be visible in the Cloudflare dashboard to your team members. For sensitive values, consider using the secrets approach below.
96
-
:::
97
-
98
-
### Using Secrets for Sensitive Values
99
-
100
-
To properly attach sensitive environment variables as secrets, you must use a 3-step deployment process using Wrangler's [versions commands](https://developers.cloudflare.com/workers/wrangler/commands/#versions):
101
-
102
-
1. Create a new deployment version
103
-
2. Attach the secret
104
-
3. Activate the deployment
105
-
106
-
```bash
107
-
# Step 1: Create a version that's not deployed immediately
108
-
# and note the version id for the next steps
109
-
wrangler versions upload
110
-
111
-
# Step 2: Attach secret (using the resolved env as a single JSON object)
112
-
wrangler secret put __VARLOCK_ENV --version <version-id><<<"$(APP_ENV=prod varlock load --format json-full)"
113
-
114
-
# Step 3: Activate the deployment
115
-
wrangler versions deploy <version-id>
116
-
```
117
-
118
-
:::note[Future improvement]
119
-
Cloudflare is working on the ability to push secrets with a deploy command. See [this pull request](https://github.com/cloudflare/workers-sdk/pull/10896) for updates.
120
-
:::
121
-
122
-
---
123
-
124
-
## Approach 2: Using Wrangler Vars and Secrets (Without Vite)
125
-
126
-
If you prefer not to use the Vite plugin, you can use Wrangler's built-in environment variable handling. Note that this approach will not provide varlock's security features like leak detection and log redaction.
127
-
128
-
### Local Development
129
-
130
-
For local development, you can use `varlock run` to inject resolved environment variables:
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).
131
100
132
101
```diff lang="json" title="package.json"
133
102
{
134
103
"scripts": {
135
-
- "dev": "wrangler dev",
136
-
+ "dev": "env -i PATH="$PATH" varlock run -- <command>",
Because you're creating a child process with a 'clean' environment, you may need to explicitly include any system level env vars that you need.
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.
143
112
:::
144
113
145
-
### Deployment
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):
146
117
147
-
For deployments using Wrangler's built-in environment variables, you'll need to use the 3-step deployment process with `secret bulk`:
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
148
121
149
122
```bash
150
123
# Step 1: Create a version that's not deployed immediately
151
-
#and note the version id for the next steps
152
-
wrangler versions upload
124
+
# note the empty __VARLOCK_ENV so it will not reuse existing config
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
+
:::
162
137
163
-
## Accessing Environment Variables
138
+
## Accessing environment variables
164
139
165
-
Regardless of which approach you use, we recommend using varlock's `ENV` object instead of Cloudflare's built-in environment variable access:
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:
166
141
167
142
```ts title="src/index.ts"
168
-
import { ENV } from'varlock/env';
169
-
170
-
exportdefault {
171
-
async fetch(request:Request):Promise<Response> {
172
-
// ❌ Not recommended - uses Cloudflare's built-in env
173
-
// const apiKey = env.API_KEY;
143
+
// ❌ Do not use Cloudflare's built-in env
144
+
import { env } from"cloudflare:workers";
145
+
console.log(env.API_KEY);
174
146
175
-
// ✅ Recommended - uses varlock's ENV
176
-
const apiKey =ENV.API_KEY;
177
-
178
-
returnnewResponse('Hello World');
179
-
},
180
-
};
147
+
// ✅ Recommended - uses varlock's ENV
148
+
import { ENV } from'varlock/env';
149
+
console.log(ENV.API_KEY);
181
150
```
182
151
183
-
### Why use `ENV` instead of Cloudflare's built-in env?
184
-
185
-
- Non-string values (e.g., number, boolean) are properly typed and coerced
186
-
- Better error messages for invalid or unavailable keys
187
-
- Type safety and IntelliSense support
188
-
- Security features like leak detection and log redaction (if using the Vite plugin)
189
-
- Consistent API across different deployment platforms
190
-
191
152
---
192
153
193
154
## Managing Multiple Environments
194
155
195
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).
196
157
197
-
You can use Cloudflare's branch name to determine the environment:
158
+
If you are using Cloudflare's CI, you can use the current branch name (`WORKERS_CI_BRANCH`) to determine the environment:
Copy file name to clipboardExpand all lines: packages/varlock-website/src/content/docs/integrations/overview.mdx
+14-13Lines changed: 14 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,21 +6,22 @@ description: How Varlock integrates with popular frameworks, bundlers, and runti
6
6
Varlock ships with official integrations that wire the CLI, runtime helpers, and framework-specific plugins together so your configuration is validated, type-safe, and protected everywhere it runs.
7
7
8
8
Integrations allow you to:
9
-
- load and validate `.env` files automatically during dev and use them in CI/CD and production.
10
-
- inject config into your code at build or request time.
11
-
- enable runtime protections such as leak prevention, and log redaction.
9
+
- load and validate `.env` files automatically during dev and use them in CI/CD and production
10
+
- inject config into your code at build or request time
11
+
- enable runtime protections such as leak prevention, and log redaction
12
12
13
13
## Official integrations
14
-
-[JavaScript / Node.js](/integrations/javascript/) — use `varlock` in custom toolchains, scripts, and servers.
15
-
-[Next.js](/integrations/nextjs/) — drop-in replacement for `@next/env`.
16
-
-[Vite](/integrations/vite/) — Vite plugin that validates and replaces at build time.
17
-
-[Qwik](/integrations/vite/) — Use the Vite integration.
18
-
-[React Router](/integrations/vite/) — Use the Vite integration.
19
-
-[Cloudflare Workers](/integrations/cloudflare/) — Use the Vite integration or Wrangler vars/secrets directly.
20
-
-[Astro](/integrations/astro/) — Astro integration built on top of our Vite plugin.
21
-
-[GitHub Actions](/integrations/github-action/) — Validate your `.env.schema` in GitHub Actions workflows
22
-
-[Other languages](/integrations/other-languages/) — guidance for piping varlock output into non-JS runtimes.
23
-
-[Docker](/guides/docker/) — A Docker wrapper around the varlock CLI including examples.
14
+
-[JavaScript / Node.js](/integrations/javascript/) — use `varlock` in custom toolchains, scripts, and servers
15
+
-[Bun](/integrations/bun/) — instructions to set up Varlock with Bun
16
+
-[Next.js](/integrations/nextjs/) — drop-in replacement for `@next/env`
17
+
-[Vite](/integrations/vite/) — Vite plugin that validates and replaces at build time
18
+
-[Qwik](/integrations/vite/) — use the Vite integration
19
+
-[React Router](/integrations/vite/) — use the Vite integration
20
+
-[Cloudflare Workers](/integrations/cloudflare/) — use the Vite integration or Wrangler vars/secrets directly
21
+
-[Astro](/integrations/astro/) — Astro integration built on top of our Vite plugin
22
+
-[GitHub Actions](/integrations/github-action/) — validate your `.env.schema` in GitHub Actions workflows
23
+
-[Other languages](/integrations/other-languages/) — guidance for piping varlock output into non-JS runtimes
24
+
-[Docker](/guides/docker/) — a Docker wrapper around the varlock CLI including examples
0 commit comments