Next.js Environment Variables: Encrypted Secrets

Capy works with Next.js across every runtime (Node, Edge) and every deploy target (Vercel, self-hosted). Wrap next dev and next build with capy run and read process.env as you always have.

Install the CLI

brew install capysc/tap/capy

npm install -g @capysc/cli

bun add -g @capysc/cli

Also add it as a dev dependency so your deploy platform installs it during builds:

bun add -D @capysc/cli

Sync your secrets

From a project that has a .env:

capy

Capy authenticates you, creates a project on first run, encrypts every value in .env, and gitignores the file. Only keep.lock (a small versioning manifest) is committed.

Wrap dev and build in package.json

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

bun run dev / npm run dev / pnpm dev all work as usual. capy run decrypts .env in memory and hands plaintext values to Next via process.env. Both Node and Edge routes read them the standard way:

const db = process.env.DATABASE_URL;

Invite a teammate

capy invite teammate@example.com

Capy prints a one-line redeem code. Send it out-of-band. They run capy redeem <code> and now share access.

Deploy to Vercel

Run:

capy deploy

Pick Vercel at the platform prompt. Vercel has a connector, so Capy then asks what you want to do. Pick Set up CI deploy token + docs (capy run in your CI) for the build-time flow described here. The other option, Deploy now via connector, takes a different route: it pushes each value into Vercel’s own environment-variable store with the vercel CLI, so the build reads them natively and needs no capy run step.Capy mints two environment variables - SECRETS_BLOB and PROJECT_KEY - and opens a temporary page on 127.0.0.1 in your browser showing both values plus Vercel-specific instructions (if it can’t start that local page, it prints the two values in the terminal instead; if the page starts but your browser doesn’t launch, Capy prints the 127.0.0.1 URL for you to open yourself). Paste them into your Vercel project’s Settings → Environment Variables (or vercel env add). Set the same pair on Preview / Development if you want Capy to decrypt there too. Press Ctrl+C to close the page when you’re done.To skip both prompts, run capy deploy --platform vercel --mode token.Next, point next.config.js at Capy’s auto-generated env map. capy run writes .capy/next-env.js only in deployed mode - when both SECRETS_BLOB and PROJECT_KEY are set - and .capy/ is gitignored, so guard the require or a local next dev will fail on the missing file:

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

const envPath = join(__dirname, ".capy", "next-env.js");
const capyEnv = existsSync(envPath) ? require(envPath) : {};

module.exports = {
  env: capyEnv,
};

That’s it. On every vercel deploy:

Vercel clones your branch, installs @capysc/cli, runs capy run -- next build.
capy run sees SECRETS_BLOB + PROJECT_KEY, enters deployed mode, calls Capy’s service to reconstruct the decrypt key, expands the blob into individual env vars, and writes .capy/next-env.js listing them.
next build runs with plaintext env vars set, and Next inlines every variable named in the env field as a string literal in the compiled bundle.
Runtime functions (Node and Edge) read the inlined literals. No runtime decryption, no service call per request.

SECRETS_BLOB carries an encrypted snapshot of .env taken when you ran capy deploy, so adding a secret and running capy does not change what the deployed build sees. To ship a new secret, re-run capy deploy, update the values in Vercel, and redeploy - next-env.js is regenerated from the new blob, so next.config.js never churns.

Edge vs. Node routes

Both work the same way. In a deployed build, Capy values land in process.env at build time via Next’s env config, and Next replaces process.env.X references with string literals during compilation. The resulting code has no runtime env lookup, so it runs identically in Node and Edge isolates.

App Router, Pages Router, Middleware

All three read from process.env the standard way. No Capy-specific imports, no initialization call, no runtime library. The only Capy touchpoints in the Next codebase are the env map wired into next.config.js and the capy run -- wrappers in package.json.

Self-hosted Next.js

Skip the next.config.js change and the Vercel env vars. Just set capy run as the process entrypoint:

capy run -- next start

Without SECRETS_BLOB and PROJECT_KEY, capy run decrypts the .env in the working directory, which also needs the project’s keep.lock there. On a cloud or BYOC profile it resolves the project key through Capy’s service on every run, so you have to be signed in and the service has to be reachable; on a local-only profile it resolves the key offline and prompts for your passphrase when the local key is locked. If you set SECRETS_BLOB and PROJECT_KEY on the box instead (containers, long-running servers), capy run takes the deployed path and never reads .env. Set both or neither - with only one set it refuses to run.

Getting started

Using Capy

Deploying

Organizations

Branches

Team

CLI reference

Under the hood

Comparisons

Next.js Environment Variables: Encrypted Secrets

Edge vs. Node routes

App Router, Pages Router, Middleware

Self-hosted Next.js

What’s next

Deploying

capy run

​Edge vs. Node routes

​App Router, Pages Router, Middleware

​Self-hosted Next.js

​What’s next

Deploying

capy run

Edge vs. Node routes

App Router, Pages Router, Middleware

Self-hosted Next.js

What’s next