Vercel + Next.js Environment Variables (Encrypted)

​

Setup (once per project)

1. Add Capy’s CLI as a dep so Vercel installs it during build:
   bun add -D @capysc/cli
   
2. Wrap your build (and dev) in package.json:
   {
     "scripts": {
       "dev": "capy run -- next dev",
       "build": "capy run -- next build"
     }
   }
   
3. Point next.config.js at the generated env map. During the build, capy run writes .capy/next-env.js - a CommonJS module mapping every variable name it decrypted from SECRETS_BLOB to its process.env reference. Capy only writes that file in deployed mode (both SECRETS_BLOB and PROJECT_KEY set), and it gitignores .capy/, so guard the require or a local next dev fails 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 - no hand-maintained list. next-env.js regenerates on every build from whatever the blob holds, so a newly deployed variable reaches your code without touching next.config.js.
4. Run capy deploy and pick Vercel at the platform prompt. Vercel has a connector, so Capy asks what you want to do next - pick Set up CI deploy token + docs (capy run in your CI) for the build-time flow on this page. The other option, Deploy now via connector, takes a different route: it decrypts the current branch locally and pushes the vars you select into Vercel’s own environment-variable store with the vercel CLI, then opens a keep.lock PR that Vercel’s git integration builds on merge - no SECRETS_BLOB, no capy run in the build. capy deploy --platform vercel --mode token skips both prompts. Capy mints two env vars - 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 open that page it prints the two values in the terminal instead. Paste them into Settings → Environment Variables in the Vercel dashboard (or vercel env add SECRETS_BLOB production / vercel env add PROJECT_KEY production). Repeat for Preview and Development if you want Capy to decrypt there too. Press Ctrl+C to close the page when you’re done; it also shuts itself down after five minutes.
5. Deploy. Vercel clones your branch, installs @capysc/cli, runs capy run -- next build, and the resulting bundle has your runtime values baked in. Both Node and Edge routes read them normally.

​

What happens during the build

• Runtime functions do zero crypto - they read already-inlined constants.
• Edge / Node / any framework - the mechanism is just process.env.
• One service call per build, not per request.
• Revocation = redeploy. Intentional; no caches to chase.

​

Local development

capy run -- next dev