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
description: Introduction to varlock - declarative schema for your environment variables
3
+
description: Introduction to Varlock - declarative schema for your environment variables
4
4
---
5
5
6
-
Varlock is a framework-agnostic, universal environment variable management tool built on top of the [@env-spec](/env-spec/overview) specification. It provides a comprehensive set of features out of the box that simplify managing, validating, and securing your environment configuration. Whether you need type-safe environment variables, multi-environment management, secure secret handling, or leak prevention, varlock lets you focus on building your application instead of wrestling with configuration.
6
+
Varlock is a universal configuration/secrets/environment variable management tool built on top of the [@env-spec](/env-spec/overview/) specification. It provides a comprehensive set of features out of the box that simplify managing, validating, and securing your environment configuration. Whether you need type-safe environment variables, multi-environment management, secure secret handling, or leak prevention, Varlock lets you focus on building your application instead of wrestling with configuration. While it is written in TypeScript, it is language and framework agnostic, and meant to be used in any project that needs configuration at build or boot time, usually passed in via environment variables.
7
7
8
8
## Features
9
9
10
10
Varlock aims to be the most comprehensive environment variable management tool. It provides a wide range of features out of the box:
11
11
12
-
-**[Validation & Type Safety](/reference/data-types)** - Powerful validation capabilities with clear error messages, plus automatic type generation for IntelliSense support
13
-
-**[Security](/guides/secrets)** - Automatic log redaction for sensitive values and leak detection in bundled code and server responses
14
-
-**[Multi-Environment Management](/guides/environments)** - Flexible environment handling with support for environment-specific files, local overrides, and value composition
15
-
-**[Secure Secrets](/guides/secrets)** - Load secrets from external providers like [1Password](/plugins/1password) via [plugins](/plugins/overview) or any CLI tool using [function calls](/reference/functions)
16
-
-**[Value Composition](/reference/functions)** - Compose values together using functions, references, and external data sources
17
-
-**[Framework Integrations](/integrations/overview)** - Official integrations for Next.js, Vite, Astro, and more, plus support for any language via `varlock run`
18
-
-**[Replacement for dotenv](/guides/migrate-from-dotenv)** - Can be used as a direct replacement for `dotenv` in most projects with minimal code changes
19
-
-**[AI-Friendly](/guides/ai-tools)** - Built with AI-assisted development in mind, helping prevent accidental secret leaks to AI agents and allowing a schema-driven approach that is easier for AI to understand and remediate.
12
+
-**[Validation & Type Safety](/reference/data-types/)** - Powerful validation capabilities with clear error messages, plus automatic type generation for IntelliSense support
13
+
-**[Security](/guides/secrets/)** - Automatic log redaction for sensitive values and leak detection in bundled code and server responses
14
+
-**[Multi-Environment Management](/guides/environments/)** - Flexible environment handling with support for environment-specific files, local overrides, and value composition
15
+
-**[Secure Secrets](/guides/secrets/)** - Load secrets from external providers like [1Password](/plugins/1password/) via [plugins](/plugins/overview/) or any CLI tool using [exec()](/reference/functions/#exec)
16
+
-**[Value Composition](/reference/functions/)** - Compose values together using functions, references, and external data sources
17
+
-**[Framework Integrations](/integrations/overview/)** - Official integrations for Next.js, Vite, Astro, and more, plus support for any language via `varlock run`
18
+
-**[Replacement for dotenv](/guides/migrate-from-dotenv/)** - Can be used as a direct replacement for `dotenv` in most projects with minimal code changes
19
+
-**[AI-Friendly](/guides/ai-tools/)** - Built with AI-assisted development in mind, helping prevent accidental secret leaks to AI agents and allowing a schema-driven approach that is easier for AI to understand and remediate
20
20
21
21
## AI Tooling
22
22
23
23
### Docs MCP
24
24
25
-
Varlock provides a Docs MCP server that allows AI tools to search and understand the Varlock documentation. This makes it easier for AI assistants to help you integrate and use varlock in your projects.
25
+
Varlock provides a Docs MCP server that allows AI tools to search and understand the Varlock documentation. This makes it easier for AI assistants to help you integrate and use Varlock in your projects.
26
26
27
27
See the [MCP guide](/guides/mcp/#docs-mcp) for setup instructions for Cursor, Claude, Opencode, VS Code, and other MCP-compatible tools.
28
28
@@ -32,5 +32,5 @@ Varlock also provides an `LLMs.txt` file that helps AI models understand how to
32
32
33
33
## Next Steps
34
34
35
-
Ready to get started? Check out the [Installation](/getting-started/installation) guide to set up varlock in your project.
35
+
Ready to get started? Check out the [Installation](/getting-started/installation/) guide to set up Varlock in your project.
In most [Node.js](/integrations/javascript) apps, you can replace `dotenv/config` with `varlock/auto-load` after [installing varlock](/getting-started/installation).
10
+
### Migration from dotenv (Node.js)
11
+
12
+
In a [Node.js](/integrations/javascript/) app if you are already calling `dotenv/config`, you can replace it with `varlock/auto-load`.
11
13
12
14
```diff title="index.js" lang="js"
13
-
// Before (dotenv)
14
15
- import 'dotenv/config';
15
-
16
-
// After (varlock)
17
16
+ import 'varlock/auto-load';
18
17
```
19
18
20
-
See our [migrate from dotenv](/guides/migrate-from-dotenv) guide for more information.
19
+
In some cases where `dotenv` is being called deep under the hood by another dependency, you may instead want to swap it in as a dependency override. See our [migrate from dotenv](/guides/migrate-from-dotenv/) guide for more information.
20
+
21
+
### Within a framework
22
+
23
+
We must replace framework's existing `.env` logic with Varlock. Our [framework integrations](/integrations/overview/) handle most of the work for you. After [installation](/getting-started/installation/), simply follow the instructions in the relevant integration guide to set up Varlock in your project. Usually this involves adding a new plugin to the existing build system or framework's config file.
24
+
25
+
### Minimal setup
26
+
27
+
In some cases, a code-level integration may be challenging or impossible. In this case you can use [`varlock run`](/reference/cli-commands/#run) to boot your application with env vars injected from Varlock. For example `varlock run -- your-app`. Sometimes you may need to use this alongside a deeper integration, for example to feed env vars into external tools or additional scripts.
28
+
29
+
21
30
22
-
## From specific integrations
31
+
## Using `varlock/env`
23
32
24
-
If you're currently using `import.meta.env` or `process.env`, your code will still work after switching to varlock. However, we recommend using varlock's `ENV` object for better type-safety and improved developer experience.
33
+
If you're currently using `import.meta.env` or `process.env`, your code will still work after switching to Varlock. However, we recommend using varlock's `ENV` object for better type-safety and an improved developer experience.
25
34
26
35
```diff title="index.js" lang="js"
27
36
// Before (import.meta.env)
@@ -34,4 +43,4 @@ import { ENV } from 'varlock/env';
1. Run `varlock init` to set up your `.env.schema` file(s)
13
-
2. Run `varlock load` to validate your environment variables
14
-
3. Run `varlock run` to valid and inject your environment variables into your command
12
+
1. Run [`varlock init`](/reference/cli-commands/#init) to set up your `.env.schema` file
13
+
2. Run [`varlock load`](/reference/cli-commands/#load) to debug and refine your .env file(s)
14
+
3. Use Varlock to load, validate, and inject env vars into your application, either:
15
+
- Use an [existing framework / tool integration](/integrations/overview/) that automatically calls Varlock under the hood (_recommended_)
16
+
- Use `import 'varlock/auto-load'` in a backend JavaScript/TypeScript project
17
+
- Boot your command via [`varlock run`](/reference/cli-commands/#run)<br/>(_necessary for non-JS/TS projects, or feeding env vars to external tools_)
15
18
16
19
17
-
:::tip
18
-
In most cases, you'll want to use an integration to handle the loading and validation of environment variables for you. See the [Integrations](/integrations/overview) section for more information.
19
-
:::
20
-
21
20
## CLI Commands
22
21
23
22
### `varlock load`
@@ -26,14 +25,14 @@ In most cases, you'll want to use an integration to handle the loading and valid
26
25
27
26
Validates your environment variables according to your `.env.schema` and associated `.env.*` files, and prints the results.
28
27
29
-
Useful for debugging locally, and in CI to print out a summary of env vars, also when you're authoring your `.env.schema` file and want immediate feedback.
28
+
Useful for debugging locally, and in CI to print out a summary of env vars, also when you're authoring your `.env.schema` file and want immediate feedback.
30
29
31
30
:::tip
32
31
Our [integrations](/integrations/overview) all use `varlock load` under the hood, so you'll get the same developer experience, but typically they will only let you know if there are errors, rather than the full summary.
33
32
:::
34
33
35
34
36
-
See the [`varlock load` CLI Reference](/reference/cli-commands/#varlock-load) for more information.
35
+
See the [`varlock load` CLI Reference](/reference/cli-commands/#load) for more information.
37
36
38
37
### `varlock run`
39
38
@@ -42,4 +41,4 @@ See the [`varlock load` CLI Reference](/reference/cli-commands/#varlock-load) fo
42
41
Executes a command in a child process, injecting your resolved and validated environment variables. This is useful when a code-level integration is not possible. For example, if you're using a database migration tool, you can use `varlock run` to run the migration tool with the correct environment variables. Or if you're using a non-js/ts language, you can use `varlock run` to run a command and inject validated environment variables.
43
42
44
43
45
-
See the [`varlock run` CLI Reference](/reference/cli-commands/#varlock-run) for more information.
44
+
See the [`varlock run` CLI Reference](/reference/cli-commands/#run) for more information.
With a more flexible env var toolkit, after an initial migration, you may be tempted to take advantage
11
+
of Varlock's features to improve your developer experience and security posture.
12
+
13
+
- Move more configuration constants out of application code and into your `.env` files
14
+
- Reduce the number of of env-style checks in your code, favouring individual flags, with a default value set based on the current env
15
+
- Add deeper validation, more thorough comments, and additional docs links to each env var within your schema
16
+
- Compose values together to keep your configuration DRY
17
+
- Use [imports](/guides/import/) to share common configuration across a monorepo, or to break up a large `.env.schema`
18
+
- Reduce secret sprawl, by loading secrets from a single source of truth, instead of injecting them from your CI/hosting platform
19
+
20
+
21
+
## Repo setup
9
22
10
23
### `.gitignore`
11
24
12
25
Depending on your setup you will want to update your `.gitignore` to _not_ ignore your `.env.schema` file and any other `.env.xxx` files that can now be safely committed to your repo if they don't contain secrets (which they shouldn't).
13
26
14
-
We also recommend that you ignore `env.d.ts` as it is dynamically generated based the hierarchy of env files being loaded on each individual machine.
27
+
If using [generated types](/reference/root-decorators/#generatetypes), we also recommend that you ignore the generated file (usually `env.d.ts`in TypeScript) as it is dynamically generated based the hierarchy of env files being loaded on each individual machine.
15
28
16
29
```diff title=".gitignore"
17
-
# Include .env.schema file
18
-
+!.env.schema
19
-
# Exclude env.d.ts
30
+
31
+
# Include .env.schema, .env.<dev|preview|prod|...> file
32
+
# exclude local overrides
33
+
-.env.*
34
+
+.env.local
35
+
+.env.*.local
36
+
37
+
# Exclude generated env types file
20
38
+env.d.ts
21
39
```
22
40
23
41
:::tip
24
-
Depending on the [AI Tools](/guides/ai-tools) you use, you may need to add a similar rule to allow `.env.schema` to be modified. For example, in `.cursorignore`.
42
+
Depending on the [AI Tools](/guides/ai-tools/) you use, you may need to add a similar rule to allow `.env.schema` to be modified. For example, in `.cursorignore`.
25
43
:::
26
44
27
45
### Monorepos
28
46
29
-
Consider how you can reuse and modularize your schema if you have a monorepo or multi-service setup. See the [Imports](/guides/import) guide for more information.
47
+
Consider how you can reuse and modularize your schema if you have a monorepo or multi-service setup. See the [Imports](/guides/import/) guide for more information.
30
48
31
49
## Deployment
32
50
33
51
### CI/CD platforms
34
52
35
-
It may be useful to validate your schema in CI/CD pipelines, especially if you want to validate configurations that you don't have access to locally (e.g. Staging or Production). You can do this manually by running `varlock load` in your pipeline. And if you're using GitHub Actions, you can use the [Varlock GitHub Action](/integrations/github-action) to validate your schema automatically.
53
+
It may be useful to validate your schema in CI/CD pipelines, especially if you want to validate configurations that you don't have access to locally (e.g. Staging or Production). You can do this manually by running `varlock load` in your pipeline. And if you're using GitHub Actions, you can use the [Varlock GitHub Action](/integrations/github-action/) to validate your schema automatically.
36
54
37
55
:::tip
38
-
Having a well architected multi-environment setup is key to healthy CI/CD workflows. See the [Environments](/guides/environments) guide for more information.
56
+
Having a well architected multi-environment setup is key to healthy CI/CD workflows. See the [Environments](/guides/environments/) guide for more information.
39
57
:::
40
58
41
59
### Production deployments
42
60
43
-
Because varlock supports loading environment variables from the environment itself or via a [function](/reference/functions/) in your `.env.schema`, there are a few different approaches.
61
+
Because varlock supports loading environment variables from the environment itself or via a [function](/reference/functions/) in your `.env.schema`, there are a few different approaches.
44
62
45
63
If you're already using your deployment platform's environment variable management, you may not need to do anything to benefit from varlock's validation and security features. If you have a multi-environment setup, you may need to set the `currentEnv` environment flag to the correct environment.
46
64
47
65
```bash
48
66
APP_ENV=production varlock run -- your-production-command
49
67
```
50
68
51
-
If you're not using your deployment platform's environment variable management, you may consider using one of our [plugins](/plugins/overview) to securely load environment variables from a secret storage system such as [1Password](/plugins/1password/).
69
+
If you're not using your deployment platform's environment variable management, you may consider using one of our [plugins](/plugins/overview/) to securely load environment variables from a secret storage system such as [1Password](/plugins/1password/).
Copy file name to clipboardExpand all lines: packages/varlock-website/src/content/docs/guides/telemetry.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -68,4 +68,4 @@ The anonymous usage data helps us:
68
68
- Make informed decisions about future development
69
69
- Prioritize bug fixes and new features
70
70
71
-
If you have any questions about our analytics or privacy practices, please [start a discussion](https://github.com/dmno-dev/varlock/discussions) on GitHub.
71
+
If you have any questions about our analytics or privacy practices, please [start a discussion](https://github.com/dmno-dev/varlock/discussions) on GitHub.
Copy file name to clipboardExpand all lines: packages/varlock-website/src/content/docs/integrations/nextjs.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -299,7 +299,7 @@ _you may need to adjust if you don't want to copy certain .local files_
299
299
300
300
301
301
Standalone builds do not copy dependency binaries, and varlock depends on the CLI to load.
302
-
So wherever you are booting your standalone server, you will also need to [install the varlock binary](/getting-started/installation/) and boot your server via [`varlock run`](/reference/cli-commands/#varlock-run)
302
+
So wherever you are booting your standalone server, you will also need to [install the varlock binary](/getting-started/installation/) and boot your server via [`varlock run`](/reference/cli-commands/#run)
Copy file name to clipboardExpand all lines: packages/varlock-website/src/content/docs/integrations/other-languages.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ import ExecCommandWidget from "@/components/ExecCommandWidget.astro";
7
7
8
8
To use varlock with other languages, you'll likely want to [install the standalone binary](/getting-started/installation/#as-a-binary), rather than using a JS package manager.
9
9
10
-
To use it with your application code, you must use [`varlock run`](/reference/cli-commands/#varlock-run) to load and validate your environment variables, then run the command you provided with those environment variables injected into the process.
10
+
To use it with your application code, you must use [`varlock run`](/reference/cli-commands/#run) to load and validate your environment variables, then run the command you provided with those environment variables injected into the process.
0 commit comments