Astro

While Astro has astro:env to help with environment variables, we think Varlock has more to offer:

• Your .env.schema is not tied to JavaScript, and is a better place to store this schema info versus your astro.config.* file
• Facilitates loading and composing multiple .env files
• You can use validated env vars right away within your astro.config.* file
• Facilitates setting values and handling multiple environments, not just setting defaults
• More data types and options available
• Leak detection, log redaction, and more security guardrails

To integrate varlock into an Astro application, you must use our @varlock/astro-integration package, which is an Astro integration.

Setup

Requirements

• Node.js v22 or higher
• Astro v4 or higher

1. Install varlock and the Astro integration package

   npm

   npm install @varlock/astro-integration varlock

   pnpm

   pnpm add @varlock/astro-integration varlock

   bun

   bun add @varlock/astro-integration varlock

   yarn

   yarn add @varlock/astro-integration varlock

   vlt

   vlt install @varlock/astro-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. Enable the Astro integration

   You must add our varlockAstroIntegration to your astro.config.* file:

   astro.config.ts

   import { defineConfig } from 'astro/config';
   import varlockAstroIntegration from '@varlock/astro-integration';
   
   export default defineConfig({
     integrations: [varlockAstroIntegration(), otherIntegration()],
   });

---

Accessing environment variables

You can continue to use import.meta.env.SOMEVAR as usual, but we recommend using varlock’s imported ENV object for better type-safety and improved developer experience:

example.ts

import { ENV } from 'varlock/env';

console.log(import.meta.env.SOMEVAR); // 🆗 still works
console.log(ENV.SOMEVAR);             // ✨ recommended

Why use ENV instead of import.meta.env?

• Non-string values (e.g., number, boolean) are properly typed and coerced
• All non-sensitive items are replaced at build time (not just VITE_ prefixed ones)
• Better error messages for invalid or unavailable keys
• Enables future DX improvements and tighter control over what is bundled

Within astro.config.*

It’s often useful to be able to access env vars in your Astro config. Without varlock, it’s a bit awkward, but varlock makes it easy. In fact it’s already available: import varlock’s ENV object and reference env vars via ENV.SOME_ITEM like you do everywhere else.

astro.config.ts

import { defineConfig } from 'astro/config';
import varlockAstroIntegration from '@varlock/astro-integration';
import { ENV } from 'varlock/env';

doSomethingWithEnvVar(ENV.FOO);

export default defineConfig({ /* ... */ });

TypeScript config

If you find you are not getting type completion on ENV, you may need to add your generated type files (usually env.d.ts) to your tsconfig.json’s include array.

Within other scripts

Even in a static front-end project, you may have other scripts in your project that rely on sensitive config.

You can use varlock run to inject resolved config into other scripts as regular env vars.

npm

npm exec -- varlock run -- node ./script.js

pnpm

pnpm exec -- varlock run -- node ./script.js

bun

bunx varlock run -- node ./script.js

vlt

vlx -- varlock run -- node ./script.js

yarn

yarn exec -- varlock run -- node ./script.js

Type-safety and IntelliSense

To enable type-safety and IntelliSense for your env vars, enable the @generateTsTypes root decorator in your .env.schema. Note that if your schema was created using varlock init, it will include this by default.

.env.schema

# @generateTsTypes(path='env.d.ts')
# ---
# your config items...

---

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. This is different than Astro/Vite’s default behaviour, which relies on it’s own MODE flag.

Usually this env var will be defaulted to something like development in your .env.schema file, and you can override it by overriding the value when running commands - for example APP_ENV=production vite build. For a JavaScript based project, this will often be done in your package.json scripts.

package.json

{
  "scripts": {
    "dev": "astro dev",
    "build": "APP_ENV=production astro build",
    "preview": "APP_ENV=production vite preview",
  }
}

In some cases, you could also set the current environment value based on other vars already injected by your CI platform, like the current branch name. See the environments guide for more information.

Managing sensitive config values

Astro uses the PUBLIC_ prefix to determine which env vars are public (bundled for the browser). Varlock decouples the concept of being sensitive from key names, and instead you control this with the @defaultSensitive root decorator and the @sensitive item decorator. See the secrets guide for more information.

Set a default and explicitly mark items:

.env.schema

# @defaultSensitive=false
# ---
NON_SECRET_FOO= # sensitive by default
# @sensitive
SECRET_FOO=

Or if you’d like to continue using Astro’s prefix behavior:

.env.schema

# @defaultSensitive=inferFromPrefix('PUBLIC_')
# ---
FOO= # sensitive
PUBLIC_FOO= # non-sensitive, due to prefix

Bundling behavior

All non-sensitive items are bundled at build time via ENV, while import.meta.env replacements continue to only include PUBLIC_-prefixed items.

Leak Detection

This integration will automatically inject a new middleware that scans outgoing http responses for any sensitive values.

Encrypting the env blob

When deploying SSR Astro apps to serverless platforms, varlock injects the resolved env into your server-side build output as plaintext JSON. This is generally safe since it only appears in server code, but you can encrypt it for extra protection (e.g., against sourcemap leaks). See the encrypted deployments guide for setup instructions.

---

Deploying to Cloudflare Workers

If you deploy your SSR Astro app to Cloudflare Workers via @astrojs/cloudflare, install @varlock/cloudflare-integration alongside the Astro integration. The Astro integration auto-detects the Cloudflare adapter and wires up env injection into the worker. There’s no extra Vite or adapter config to write, and you keep using astro dev as normal.

Static and prerendered pages work too: they are rendered at build time with your resolved env, so a fully static site (output: 'static') needs no vars or secrets uploaded to Cloudflare at all.

1. Install the Cloudflare integration

   npm

   npm install @varlock/cloudflare-integration

   pnpm

   pnpm add @varlock/cloudflare-integration

   bun

   bun add @varlock/cloudflare-integration

   yarn

   yarn add @varlock/cloudflare-integration

   vlt

   vlt install @varlock/cloudflare-integration

2. Use the Cloudflare adapter as usual

   No varlock-specific Cloudflare setup is needed. Use the standard adapter alongside varlockAstroIntegration():

   astro.config.ts

   import { defineConfig } from 'astro/config';
   import cloudflare from '@astrojs/cloudflare';
   import varlockAstroIntegration from '@varlock/astro-integration';
   
   export default defineConfig({
     output: 'server',
     adapter: cloudflare(),
     integrations: [varlockAstroIntegration()],
   });

3. Deploy with varlock-wrangler

   Use varlock-wrangler so your resolved env is uploaded as Cloudflare vars and secrets at deploy time:

   package.json

   {
     "scripts": {
       "dev": "astro dev",
       "build": "astro build",
       "deploy": "astro build && varlock-wrangler deploy"
     }
   }

Requires nodejs_compat

Varlock relies on a handful of node:* built-ins at runtime, so your worker must enable Cloudflare’s Node.js compatibility layer. Add nodejs_compat to compatibility_flags in your wrangler.json / wrangler.toml.

Remove .dev.vars

Varlock manages env injection automatically. Delete any .dev.vars file in your project root, or the dev server will error.

See the Cloudflare Workers integration docs for full details on how dev injection, deployment, CI/CD, and varlock-wrangler work.

Dynamic+public config

Use @dynamic to keep selected public values runtime-resolved; server-rendered code keeps reading ENV.KEY with no extra setup. See the Static vs Dynamic Config guide for the full model.

.env.schema

PUBLIC_STATIC_FLAG=enabled  # @public
PUBLIC_RUNTIME_FLAG=enabled # @public @dynamic

Client-side usage

When the schema contains any public+dynamic keys, this integration automatically injects a route at /__varlock/public-env (SSR builds only) that serves them to the browser. If browser code needs one of these values, load it with loadPublicDynamicEnv() before reading ENV.KEY; this is rarely needed, but when it is, see Loading dynamic vars in the client.

Static output

With output: 'static', the endpoint is not injected automatically during builds (it is still available in astro dev). If you use static output with an adapter (so non-prerendered routes are allowed), opt in explicitly with publicDynamicEndpoint: true. Without an adapter there is no server to serve runtime public values from.

Route injection options

You can control endpoint injection:

astro.config.ts

import { defineConfig } from 'astro/config';
import varlockAstroIntegration from '@varlock/astro-integration';

export default defineConfig({
  integrations: [
    varlockAstroIntegration({
      publicDynamicEndpoint: true, // auto by default
      // or: { path: '/my-public-env' }
      // or: false (disable auto endpoint)
    }),
  ],
});

Reference

• Root decorators reference
• Item decorators reference
• Functions reference
• Astro’s environment variable docs