Next.js Environment Variables: Encrypted Secrets

Use capy run around local Next.js commands. It gives Next decrypted values through process.env; no application SDK is required.

Install the CLI

npm install -g @capysc/cli
# or: bun add -g @capysc/cli

On macOS, Linux, and Git Bash, the release installer selects a native binary when available:

curl -fsSL https://raw.githubusercontent.com/capysc/capy-cli/main/install.sh | bash

Sync your secrets

capy

The first run authenticates you, creates or selects a Capy project, encrypts values in .env, and creates keep.lock. Commit keep.lock; it contains project metadata and hashes, not plaintext values or keys.

Wrap development commands

{
  "scripts": {
    "dev": "capy run -- next dev",
    "build": "capy run -- next build",
    "start": "capy run -- next start"
  }
}

Your app continues to read values normally:

const databaseUrl = process.env.DATABASE_URL;

Choose a deployment path

For Vercel, configure a Vercel target with capy deploy. The target writes selected values to Vercel and uses a deploy PR, so Vercel reads its normal environment variables; it does not need capy run in the build.For a platform where you control the process, use the token-and-instructions path from capy deploy, set SECRETS_BLOB and PROJECT_KEY together, and wrap the build or start command with capy run. In deployed mode, capy run writes .capy/next-env.js with variable-name lookups so Next can inline selected values at build time.

Build-time inlining

When using the runtime-pair path with next build, capy run writes .capy/next-env.js with every decrypted variable name. Do not export that whole map through Next’s env option: values in that option can be bundled into client-side code. Select only names that are intentionally public, and guard the import because local runs do not create the file.

const { existsSync } = require("fs");
const { join } = require("path");

const envPath = join(__dirname, ".capy", "next-env.js");
const capyEnv = existsSync(envPath) ? require(envPath) : {};
const publicNames = ["NEXT_PUBLIC_ANALYTICS_ID"];
const publicEnv = Object.fromEntries(
  publicNames
    .filter((name) => name in capyEnv)
    .map((name) => [name, capyEnv[name]]),
);

module.exports = { env: publicEnv };

The generated file maps names to process.env reads; it does not contain plaintext values. The explicit publicNames list is the security boundary for values Next may inline into browser output. Server-only secrets can still be read from process.env in server-side code, without adding them to env.

Self-hosted Next.js

Use a runtime pair and a wrapped entrypoint:

capy run -- next start

SECRETS_BLOB and PROJECT_KEY must both be present. With neither pair set, capy run uses the local .env and keep.lock in the working directory.

Getting started

Using Capy

Deploying

Organizations

Branches

Team

CLI reference

Under the hood

Comparisons

Next.js Environment Variables: Encrypted Secrets

Build-time inlining

Self-hosted Next.js

What’s next

Deploying

Running your app

​Build-time inlining

​Self-hosted Next.js

​What’s next

Deploying

Running your app

Build-time inlining

Self-hosted Next.js

What’s next