Integrations

Vercel Integration

@secr/vercel pulls secrets from secr and writes them to .env.local before your Vercel build runs. Works with Next.js, Vite, Remix, and any framework that reads from .env.local.

Quick Start

1. Install the package

npm install @secr/vercel

2. Create a CLI token

secr token create --name "vercel-prod"

3. Configure Vercel environment variables

In your Vercel project settings, go to Settings → Environment Variables and add the following:

Variable	Value	Environments
SECR_TOKEN	secr_tok_...	All
SECR_ORG	my-org	All
SECR_PROJECT	my-project	All

4. Update your build command

In Settings → General → Build & Development Settings, override the build command:

npx secr-vercel && next build

Replace next build with your framework's build command (e.g. vite build, remix build).

How It Works

Read environment variables — secr-vercel reads SECR_TOKEN, SECR_ORG, SECR_PROJECT, and the target environment from Vercel's environment.
Determine environment — Uses SECR_ENVIRONMENT if set, otherwise falls back to VERCEL_ENV (automatically set by Vercel to production, preview, or development).
Pull secrets — Calls the secr API using the @secr/sdk to fetch all decrypted secrets for the resolved environment.
Write .env.local — Writes the secrets as KEY=value pairs to .env.local in the working directory. Special characters and multiline values are properly escaped.
Build proceeds — Your framework reads .env.local as usual during the build step.

Environment Variables

Option	Type	Required	Description
SECR_TOKEN	string	Yes	secr CLI token (secr_tok_...). Set in Vercel project settings.
SECR_ORG	string	Yes	Organization slug in secr.
SECR_PROJECT	string	Yes	Project slug in secr.
SECR_ENVIRONMENT	string	VERCEL_ENV	Override the secr environment. Falls back to VERCEL_ENV, then to "production".
SECR_API_URL	string	https://api.secr.dev	secr API base URL.

CLI Options

Option	Type	Required	Description
--output	string	.env.local	Output file path. Defaults to .env.local in the current directory.

Custom output path

npx secr-vercel --output .env.production && next build

Environment Mapping

When SECR_ENVIRONMENT is not set, the integration uses Vercel's VERCEL_ENV value to determine which secr environment to pull from.

Vercel Context	VERCEL_ENV	secr Environment
Production	production	production
Preview	preview	preview
Development	development	development

To map Vercel's preview to a different secr environment (e.g. staging), set SECR_ENVIRONMENT=staging for the Preview environment scope in Vercel.

Troubleshooting

Error	Cause	Fix
SECR_TOKEN environment variable is required	The token is not set in Vercel project settings.	Add SECR_TOKEN to your Vercel environment variables.
SECR_ORG environment variable is required	The org slug is missing.	Add SECR_ORG to your Vercel environment variables.
Secr API error: not_found	The org, project, or environment slug does not match.	Verify slugs with secr projects list and check for typos.
Build fails but .env.local is empty	The secr-vercel command is not running before the build.	Ensure the build command is npx secr-vercel && next build (with &&).

Security Notes

•Token storage — Store the SECR_TOKEN as a sensitive environment variable in Vercel (encrypted at rest). Never commit tokens to your repository.
•.gitignore — Ensure .env.local is in your .gitignore. Next.js does this by default, but verify for other frameworks.
•Dedicated token — Create a separate token for Vercel builds. If a token is compromised, you can revoke it without affecting other services.
•Environment scoping — You can scope Vercel environment variables to specific environments (Production, Preview, Development) to limit which builds can access production secrets.

Deploy with secrets from secr

npm install @secr/vercel

Create Free Account Back to Docs