---
title: JavaScript / Node.js
description: How to integrate Varlock with JavaScript and Node.js for secure, type-safe environment management
---
import { TabItem, Tabs } from "@astrojs/starlight/components";
import ExecCommandWidget from '@/components/ExecCommandWidget.astro';

There are a few different ways to integrate Varlock into a JavaScript / Node.js application.

Some tools/frameworks may require an additional package, or have more specific instructions. Check the Integrations section in the navigation for more details.

**Want to help us build more integrations? Join our <a href={process.env.PUBLIC_DISCORD_URL}>Discord</a>!**

## Node.js - `varlock/auto-load`

The best way to integrate varlock into a plain Node.js application (⚠️ version 22 or higher) is to import the `varlock/auto-load` module. This uses `execSync` to call out to the varlock CLI, sets resolved env vars into `process.env`, and initializes varlock's runtime code, including:

- varlock's `ENV` object
- log redaction (if enabled)
- leak detection (if enabled)

```js title="example-index.js"
import 'varlock/auto-load';
import { ENV } from 'varlock/env';

const FROM_VARLOCK_ENV = ENV.MY_CONFIG_ITEM; // ✨ recommended
const FROM_PROCESS_ENV = process.env.MY_CONFIG_ITEM; // 🆗 still works
```

:::note[dotenv drop-in replacement]
If you are using [`dotenv`](https://www.npmjs.com/package/dotenv), or a package you are using is using it under the hood, you can swap in varlock using your package manager's override feature. See the [migrate from dotenv](/guides/migrate-from-dotenv) guide for more information.
:::


## Boot via `varlock run`

A less invasive way to use varlock with your application is to run your application via [`varlock run`](/reference/cli-commands/#run).

```bash
varlock run -- <your-command>
```

This will load and validate your environment variables, then run the command you provided with those environment variables injected into the process. This will not inject any runtime code, and varlock's `ENV` object will not be available.

If you have installed varlock as a project dependency instead of globally, you should run this via your package manager:
<ExecCommandWidget command="varlock run -- <your-command>" showBinary={false} />

In `package.json` scripts, calling `varlock` directly will work, as your package manager handles path issues:
```json title="package.json"
"scripts": {
  "start": "varlock run -- node index.js"
}
```

Even when using a deeper integration for your code, you may still need to use `varlock run` when calling external scripts/tools, like database migrations, to pass along resolved env vars.

:::tip[Setting the current environment]
Varlock can load multiple environment-specific `.env` files (e.g., `.env.development`, `.env.production`) by using the [`@currentEnv` root decorator](/reference/root-decorators/#currentenv) to specify which env var will set the current environment.

If not using the default (usually `development`), you'll want to pass it in as an environment variable when running your command.

```bash
APP_ENV=production varlock run -- node index.js
```

See the [environments guide](/guides/environments) for more information about how to set the current environment.
:::



## Front-end frameworks

While environment variables are not available in the browser, many frameworks expose some env vars that are available _at build time_ to the client by embedding them into your bundled code. This is best accomplished using tool-specific integrations, especially for frameworks that are handling both client and server-side code.


:::tip[Isomorphic env vars]
The `varlock/env` module is designed to be imported on both the client and server, so frameworks that run code in both places (like Next.js) can import it.
:::

<br/><br/>
:::note[Help us build more integrations!]
If you are using a tool/framework that is not listed here, and you'd like to see support for it, or collaborate on building it, we'd love to hear from you. Please hop into our <a href={process.env.PUBLIC_DISCORD_URL}>Discord</a>!
:::

