env-vars
Skill1 starsChanged 23 days agoMITView on GitHub
Vercel environment variable expert guidance. Use when working with .env files, vercel env commands, OIDC tokens, or managing environment-specific configuration.
- Reads credentials
- Installs packages
2 other projects use a version of this, 2 of them edited.
Adopted by
Most recently taken up by
- vercel/vercel-pluginedited, first seen Nov 12, 2026
- openai/pluginsedited, first seen Oct 13, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 2
- openai/plugins★ 7.8k99% same
- vercel/vercel-plugin★ 33668% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository112 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/react-best-practices/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ab-testingSkill
- ad-creativeSkill
- adsSkill
- ai-seoSkill
- analyticsSkill
- asoSkill
- attributionSkill
- auditing-experiments-flagsSkill
- churn-preventionSkill
- cleaning-up-stale-feature-flagsSkill
- cloudflareSkill
- cold-emailSkill
- co-marketingSkill
- community-marketingSkill
- competitor-profilingSkill
- competitorsSkill
- configuring-experiment-analyticsSkill
- configuring-experiment-rolloutSkill
- content-strategySkill
- copy-editingSkill
- copying-flags-across-projectsSkill
- copywritingSkill
- create-prdSkill
- creating-experimentsSkill
- croSkill
- customer-researchSkill
- deployments-cicdSkill
- diagnosing-sdk-healthSkill
- directory-submissionsSkill
- e2e-testing-patternsSkill
- eas-app-storesSkill
- eas-hostingSkill
- eas-update-insightsSkill
- eas-workflowsSkill
- emailsSkill
- eventsSkill
- expo-data-fetchingSkill
- expo-dev-clientSkill
- expo-routerSkill
- expo-upgradeSkill
- finding-experimentsSkill
- find-skillsSkill
- free-toolsSkill
- frontend-designSkill
- github-actionsSkill
- grill-with-docsSkill
- imageSkill
- infisical-apiSkill
- infisical-secret-syncsSkill
- infisical-user-setup-guideSkill
- influencer-marketingSkill
- instrument-feature-flagsSkill
- instrument-product-analyticsSkill
- investigate-metricSkill
- launchSkill
- lead-magnetsSkill
- maestro-mobile-testingSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 80
All other variables are server-only (API routes, Server Components, middleware)
- Distinctive: line 140
Use this sequence when setting up a project from scratch:
- Very specific: line 158
If you need Vercel environment variables immediately but do not want to write .env.local yet:
- Very specific: line 168
After creating/updating secrets (vercel env add, dashboard changes) or provisioning integrations that add env vars (for example …
- Very specific: line 182
Token expiry: When the local OIDC token expires, re-run vercel env pull .env.local --yes to get a fresh one.
- Very specific: line 254
Only Next.js auto-loads .env.local.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Vercel Environment Variables
You are an expert in Vercel environment variable management — .env file conventions, the vercel env CLI, OIDC token lifecycle, and environment-specific configuration.
.env File Hierarchy
Vercel and Next.js load environment variables in a specific order. Later files override earlier ones:
| File | Purpose | Git-tracked? |
.env | Default values for all environments | Yes |
.env.local | Local overrides and secrets | No (gitignored) |
.env.development | Development-specific defaults | Yes |
.env.development.local | Local dev overrides | No |
.env.production | Production-specific defaults | Yes |
.env.production.local | Local prod overrides | No |
.env.test | Test-specific defaults | Yes |
.env.test.local | Local test overrides | No |
Load Order (Next.js)
.env(lowest priority).env.[environment](development, production, or test).env.local(skipped in test environment).env.[environment].local(highest priority, skipped in test)
Critical Rules
- Never commit secrets to
.env,.env.development, or.env.production— use.localvariants or Vercel environment variables .env.localis always gitignored by Next.js — this is wherevercel env pullwrites secrets- Variables prefixed with
NEXT_PUBLIC_are exposed to the browser bundle — never put secrets inNEXT_PUBLIC_vars - All other variables are server-only (API routes, Server Components, middleware)
vercel env CLI
Pull Environment Variables
# Pull all env vars for the current environment into .env.local
vercel env pull .env.local
# Pull for a specific environment
vercel env pull .env.local --environment=production
vercel env pull .env.local --environment=preview
vercel env pull .env.local --environment=development
# Overwrite existing file without prompting
vercel env pull .env.local --yes
# Pull to a custom file
vercel env pull .env.production.local --environment=productionAdd Environment Variables
# Interactive — prompts for value and environments
vercel env add MY_SECRET
# Non-interactive
echo "secret-value" | vercel env add MY_SECRET production
# Add to multiple environments
echo "secret-value" | vercel env add MY_SECRET production preview development
# Add a sensitive variable (encrypted, not shown in logs)
vercel env add MY_SECRET --sensitiveList Environment Variables
# List all environment variables
vercel env ls
# Filter by environment
vercel env ls productionRemove Environment Variables
# Remove from specific environment
vercel env rm MY_SECRET production
# Remove from all environments
vercel env rm MY_SECRETBootstrap Flow (Fresh Clone / New Machine)
Use this sequence when setting up a project from scratch:
# 1) Link first so pulls target the correct Vercel project
vercel link --yes --project <name-or-id> --scope <team>
# 2) Pull env vars into .env.local
vercel env pull .env.local --yes
# 3) Verify required keys from .env.example exist in .env.local
while IFS='=' read -r key _; do
[[ -z "$key" || "$key" == \#* ]] && continue
grep -q "^${key}=" .env.local || echo "Missing in .env.local: $key"
done < .env.exampleTemporary Path: Run With Vercel Envs Without Writing a File
If you need Vercel environment variables immediately but do not want to write .env.local yet:
vercel env run -- npm run devThis is useful for quick validation during bootstrap, but still pull .env.local for a normal local workflow.
Re-pull After Secret or Provisioning Changes
After creating/updating secrets (vercel env add, dashboard changes) or provisioning integrations that add env vars (for example Neon/Upstash), re-run:
vercel env pull .env.local --yesOIDC Token Lifecycle
Vercel uses OIDC (OpenID Connect) tokens for secure, keyless authentication between your app and Vercel services (AI Gateway, storage, etc.).
How It Works
- On Vercel deployments:
VERCEL_OIDC_TOKENis automatically injected as a short-lived JWT and auto-refreshed — zero configuration needed - Local development:
vercel env pull .env.localprovisions aVERCEL_OIDC_TOKENvalid for ~12 hours - Token expiry: When the local OIDC token expires, re-run
vercel env pull .env.local --yesto get a fresh one. Consider re-pulling at the start of each dev session to avoid mid-session auth failures
Common OIDC Patterns
// The @vercel/oidc package reads VERCEL_OIDC_TOKEN automatically
import { getVercelOidcToken } from '@vercel/oidc'
// AI Gateway uses OIDC by default — no manual token handling needed
import { gateway } from 'ai'
const result = await generateText({
model: gateway('openai/gpt-5.2'),
prompt: 'Hello',
})Troubleshooting OIDC
| Symptom | Cause | Fix |
VERCEL_OIDC_TOKEN missing locally | Haven't pulled env vars | vercel env pull .env.local |
| Auth errors after ~12h locally | Token expired | vercel env pull .env.local --yes |
| Works on Vercel, fails locally | Token not in .env.local | vercel env pull .env.local |
AI_GATEWAY_API_KEY vs OIDC | Both set, key takes priority | Remove AI_GATEWAY_API_KEY to use OIDC |
Environment-Specific Configuration
Vercel Dashboard vs .env Files
| Use Case | Where to Set |
| Secrets (API keys, tokens) | Vercel Dashboard (https://vercel.com/{team}/{project}/settings/environment-variables) or vercel env add |
| Public config (site URL, feature flags) | .env or .env.[environment] files |
| Local-only overrides | .env.local |
| CI/CD secrets | Vercel Dashboard (https://vercel.com/{team}/{project}/settings/environment-variables) with environment scoping |
Environment Scoping on Vercel
Variables set in the Vercel Dashboard at https://vercel.com/{team}/{project}/settings/environment-variables can be scoped to:
- Production — only
vercel.appproduction deployments - Preview — branch/PR deployments
- Development —
vercel devandvercel env pull
A variable can be assigned to one, two, or all three environments.
Git Branch Overrides
Preview environment variables can be scoped to specific Git branches:
# Add a variable only for the "staging" branch
echo "staging-value" | vercel env add DATABASE_URL preview --git-branch=stagingGotchas
vercel env pull Overwrites Custom Variables
vercel env pull .env.local replaces the entire file — any manually added variables (custom secrets, local overrides, debug flags) are lost. Always back up or re-add custom vars after pulling:
# Save custom vars before pulling
grep -v '^#' .env.local | grep -v '^VERCEL_\|^POSTGRES_\|^NEXT_PUBLIC_' > .env.custom.bak
vercel env pull .env.local --yes
cat .env.custom.bak >> .env.local # Re-append custom varsOr maintain custom vars in a separate .env.development.local file (loaded after .env.local by Next.js).
Scripts Don't Auto-Load .env.local
Only Next.js auto-loads .env.local. Standalone scripts (drizzle-kit, tsx, custom Node scripts) need explicit loading:
# Use dotenv-cli
npm install -D dotenv-cli
npx dotenv -e .env.local -- npx drizzle-kit push
npx dotenv -e .env.local -- npx tsx scripts/seed.ts
# Or source manually
source <(grep -v '^#' .env.local | sed 's/^/export /') && node scripts/migrate.jsBest Practices
- Use
vercel env pullas part of your setup workflow — document it in your README - Never hardcode secrets — always use environment variables
- Scope narrowly — don't give preview deployments production database access
- Rotate OIDC tokens regularly in local dev — re-pull when you see auth errors
- Use
.env.example— commit a template with empty values so teammates know which vars are needed - Prefix client-side vars with
NEXT_PUBLIC_— and never put secrets in them - Keep custom vars in
.env.development.local— protects them fromvercel env pulloverwrites
Official Documentation
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

