Import in Your App

The runtime mode decrypts your variables in-process and hands your code a typed env object. It also populates process.env with every name that is safe to set, so libraries that read it directly keep working. No .env files on disk, no dotenv step, no process.env.X typos that silently return undefined.

Import surfaces#

@goenvless/env ships nine entry points. Three of them expose the env object, and those are the ones you choose between for reading variables:

import { env } from '@goenvless/env';          // all vars, untyped
import { env } from '@goenvless/env/server';   // all vars, fully typed
import { env } from '@goenvless/env/client';   // client-visibility vars only

The other six hand you something that isn't an env object:

Loading is asynchronous#

The store starts empty. Envless has to fetch ciphertext from the API and decrypt it locally before env has anything in it, and that's an async operation. Reading env.X before the load finishes throws:

Envless env is not loaded yet. Import '@goenvless/env/register' or await load() first.

Importing @goenvless/env or @goenvless/env/server loads nothing by itself, so there are two ways to make sure the load has happened first.

Eager preload with /register (recommended)#

@goenvless/env/register is a side-effect module that runs the loader with a top-level await. It exports nothing, and it is the only entry point that runs the loader on import. Put it first at your entry point, or inject it from the launcher:

// Runs before anything below it, env is populated by the time your code runs.
import '@goenvless/env/register';
import { env } from '@goenvless/env/server';

const db = new Database(env.DATABASE_URL);

node --import @goenvless/env/register app.js

preload = ["@goenvless/env/register"]

Or await load() before you read#

import { env, load } from '@goenvless/env/server';

await load();                       // fetch + decrypt + populate process.env
console.log(env.DATABASE_URL);

load() is memoised. Repeated calls resolve the same load exactly once, and a load that rejects clears the memo so the next call retries. The on-disk cipher cache is reused only while it is under 15 minutes old, otherwise the loader refetches. Pass load({ revalidate: true }) to force a fresh fetch, bypassing both the in-memory memo and the on-disk cipher cache.

Serialising env throws#

The env object from the root entry point and from /server cannot be turned into JSON. Neither applies a visibility filter, so one JSON.stringify would copy every decrypted secret into the output, and the usual destinations for that output are a props payload sent to the browser, a log line, or an error report on its way to a third party. It is refused instead:

import { env } from '@goenvless/env/server';

JSON.stringify(env);       // throws
JSON.stringify({ env });   // throws, stringify walks into the value
res.json(env);             // throws, Express serialises it for you

Refusing to serialise the Envless env, because it holds decrypted secrets and this would copy every one of them into the output. Read the names you need, or call load() for a plain record you own.

Do what the message says. Build the payload from the names you actually meant to send, or serialise the plain Record<string, string> that load() hands back, which is a copy you own rather than the live proxy:

import { env, load } from '@goenvless/env/server';

const payload = { region: env.AWS_REGION, tier: env.PLAN_TIER };   // name what leaves

const record = await load();                                        // a plain object, yours to serialise

/client is unaffected and serialises normally. Its proxy filters by visibility, so the JSON it produces holds client-flagged variables only, the same set the framework plugin already inlined into the bundle. The throw doesn't wait for a load either: JSON.stringify on an unloaded server env is refused exactly the same way.

Edge runtimes#

@goenvless/env/edge is the entry point for runtimes with no filesystem. It exports load(options), also available as the default export, and does the whole round trip at request time: fetch the ciphertext over the public API, import or derive the key, decrypt, and return a plain Record<string, string>.

It behaves nothing like the in-process loader. It never writes process.env, it has no in-memory memo and no on-disk cipher cache, and it reads nothing from .envless, so everything it needs arrives as an argument. envless types doesn't augment the record either, and the record holds every variable in the environment with no visibility filter, so treat it as server-side like /server.

import { load } from '@goenvless/env/edge';

export default {
    async fetch(request: Request, bindings: Record<string, string>): Promise<Response> {
        const vars = await load({
            token: bindings.ENVLESS_TOKEN,       // ev_sk_… machine key
            project: 'checkout-api',
            environment: 'production',
            key: bindings.ENVLESS_KEY            // or passphrase: bindings.ENVLESS_PASSPHRASE
        });

        return new Response(vars.STRIPE_SECRET ? 'ok' : 'missing');
    }
};

Pass neither passphrase nor key and it throws Pass { passphrase } or { key }. Without one the values cannot be decrypted. Pass a passphrase on a token whose workspace can't be resolved and it throws The workspace could not be resolved, so the passphrase cannot be turned into a key. Pass { workspaceId } explicitly.

Because nothing is cached, every load() is a fresh fetch and a fresh decrypt. Hold the returned record for the life of the isolate if you'd rather pay that once.

Boot populates process.env#

When the load resolves, decrypted values are written into process.env, but without clobbering variables that are already set. An ambient var from your shell or platform wins, matching dotenv semantics. That means anything reading raw process.env (Prisma, the AWS SDK, third-party libraries) just works, and you can still override any single value at the process level.

One set of names is refused outright. A variable called NODE_OPTIONS, NODE_PATH, NODE_REPL_EXTERNAL_MODULE, ELECTRON_RUN_AS_NODE, LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, DYLD_FRAMEWORK_PATH, PATH, BUN_INSPECT, BUN_INSPECT_CONNECT_TO, RUBYOPT, RUBYLIB, BUNDLE_GEMFILE, GEM_HOME, GEM_PATH, PYTHONPATH, PYTHONHOME, PYTHONSTARTUP, PYTHONUSERBASE, PHPRC, PHP_INI_SCAN_DIR, ENVLESS_CLIENT_ENV or ENVLESS_INJECTED is decrypted and readable through env, but never written into process.env, because those names change how the process and its children execute code. The loader prints an [envless] warning naming each one it skipped.

Setup#

npm i @goenvless/env@latest

npm i -g @goenvless/cli@latest

envless login
envless link

envless types

export ENVLESS_TOKEN=ev_sk_xxxxxxxxxxxx     # from dashboard → Keys
export ENVLESS_KEY=xxxxxxxxxxxx              # from Settings → CI / Machine Access

node --import @goenvless/env/register app.js

What the loader reads#

What you can delete#

• Your .env / .env.local / .env.development files. The loader never reads them, and anything already in the environment when the load resolves still wins as an override.
• dotenv and dotenv-cli from package.json.
• Hand-rolled process.env.X! casts and undefined checks. Names, types and visibility live in Envless, and reading a variable that isn't set throws instead of returning undefined. Envless does not validate values, so keep t3-env or envalid if you rely on the checks they run.
• .env.* entries in .gitignore.

What it looks like in practice#

import '@goenvless/env/register';
import { env } from '@goenvless/env/server';

const db = new Database({
    url: env.DATABASE_URL,          // string
    poolSize: env.DB_POOL_SIZE,     // number, coerced from the variable's type
});

const stripe = new Stripe(env.STRIPE_SECRET);

if (env.FEATURE_X_ENABLED) {        // boolean, coerced from the variable's type
    enableFeatureX();
}

Coercion follows the type you set on each variable in Envless. A number variable is passed through Number(), a boolean variable is true only for the strings true or 1, and everything else stays a string. Nothing beyond that is checked, so a number variable holding abc reads back as NaN.

Every property is autocompleted from envless-env.d.ts. Misspell one and TypeScript fails the build. Read one that isn't set and it throws Missing env var: NAME at the point you read it, never a silent undefined.

When a read is genuinely allowed to come back empty, import optional instead. Both /server and /client export it alongside env, and it is the same proxy with one rule relaxed:

import { env, optional } from '@goenvless/env/server';

const stripe = new Stripe(env.STRIPE_SECRET);                // throws if unset
if (optional.SENTRY_DSN) initSentry(optional.SENTRY_DSN);    // undefined if unset

optional is typed Partial<EnvlessServerEnv>, so your generated names come back with | undefined and TypeScript makes you handle the empty case. Values are still coerced by their declared type, the /client view still refuses server-only names, and it still throws the not-loaded error before the loader has run, so a misconfigured process fails loudly rather than reading undefined everywhere.

Framework-specific setup#

Next steps#