Skip to content
varlock

Vite

While many frameworks use Vite under the hood, some projects use Vite directly. When doing so, Vite does do some automatic loading of .env files, but it is fairly limited.

To integrate varlock into a Vite application, you must use our @varlock/vite-integration package, which is a Vite plugin.

Setup

Section titled “Setup”

  1. Install varlock and the Vite integration package

    Terminal window
    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.

    Terminal window
    npm exec -- varlock init

  3. Enable the Vite config plugin

    You must add our varlockVitePlugin to your vite.config.* file:

    vite.config.ts
    import { defineConfig } from 'vite';
    import { varlockVitePlugin } from '@varlock/vite-integration';
    

    export default defineConfig({
      plugins: [varlockVitePlugin(), otherPlugin()]
    });

Accessing environment variables

Section titled “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?

Section titled “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 vite.config.*

Section titled “Within vite.config.*”

It’s often useful to be able to access env vars in your Vite config. Without varlock, it’s a bit awkward, but varlock makes it dead simple - in fact it’s already available! Just import varlock’s ENV object and reference env vars via ENV.SOME_ITEM like you do everywhere else.

vite.config.ts
import { defineConfig } from 'vite';
import { varlockVitePlugin } from '@varlock/vite-integration';
import { ENV } from 'varlock/env';


doSomethingWithEnvVar(ENV.FOO);


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

Within HTML templates

Section titled “Within HTML templates”

Vite natively supports injecting env vars into HTML files using a special syntax like %SOME_VAR%.

This plugin injects additional replacements for strings like %ENV.SOME_VAR%.

Note that unlike the native functionality which does not replace missing/non-existant items, we will try to replace all items, and will throw helpful errors if something goes wrong.

Within other scripts

Section titled “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 environment vars.

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

Type-safety and IntelliSense

Section titled “Type-safety and IntelliSense”

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

.env.schema
# @generateTypes(lang='ts', path='env.d.ts')
# ---
# your config items...

Managing multiple environments

Section titled “Managing multiple environments”

Varlock can load multiple environment-specific .env files (e.g., .env.development, .env.preview, .env.production).

By default, vite uses its MODE flag to determine which env file(s) to load.

With varlock, instead you set your own environment flag using the @envFlag root decorator, e.g. APP_ENV. See the environments guide for more information.

Managing sensitive config values

Section titled “Managing sensitive config values”

Vite uses the VITE_ 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 Vite’s prefix behavior:

.env.schema
# @defaultSensitive=inferFromPrefix('VITE_')
# ---
FOO= # sensitive
VITE_FOO= # non-sensitive, due to prefix

Reference

Section titled “Reference”