К основному содержанию
скилл CX Codex

nextjs · bobmatnyc — скилл для Claude Code: переменные окружения Next.js

Раскладывает переменные окружения Next.js по файлам .env* и объясняет, какое значение победит при запуске, сборке и деплое.

MIT 212 установок ★ 80 обновлён 2026-07-18

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add bobmatnyc/claude-mpm-skills --skill nextjs -a claude-code
Открыть на GitHub

Что делает nextjs

Скилл описывает, как Next.js раскладывает переменные по файлам .env*: .env, .env.local, .env.development, .env.production и их .local-версии. Приоритет идёт сверху вниз: .env.$(NODE_ENV).local, .env.local (в тестах не читается), .env.$(NODE_ENV), общий .env. Если DATABASE_URL задан в двух файлах, победит более специфичный.

Дальше про типы. Всё с префиксом NEXT_PUBLIC_ уезжает в браузер, остальное живёт только на сервере: в API-роутах и getServerSideProps. Секрет в NEXT_PUBLIC_* прочитает любой, кто откроет devtools. Публичные значения вшиваются в бандл на этапе сборки, поэтому после правки их в панели Vercel нужен vercel --prod: без редеплоя в браузере останутся старые.

Внутри есть примеры .env, .env.local, .env.production и .env.example, а ещё порядок проверки: python scripts/validate_env.py .env.local --framework nextjs, сравнение с .env.example, скан утечек через python scripts/scan_exposed.py --check-gitignore и синхронизация с Vercel через python scripts/sync_secrets.py --platform vercel --sync --dry-run. Скриптам нужен Python.

Какие задачи решает

  • разложить переменные по .env, .env.local и .env.production без путаницы
  • понять, какой файл перебьёт значение в продакшене
  • убрать секреты из NEXT_PUBLIC_* до сборки
  • сверить .env.local с .env.example перед деплоем
  • перегнать локальные секреты в переменные Vercel

Примеры запросов агенту

  • Разложи переменные окружения Next.js по файлам: что в .env, что в .env.local, что в .env.production.
  • Почему в проде подхватился DATABASE_URL из .env, а не из .env.production.local?
  • Прогони scripts/validate_env.py по .env.local и сравни результат с .env.example.

Как установить nextjs

1Через Skills CLI (Vercel)

npx skills add bobmatnyc/claude-mpm-skills --skill nextjs -a claude-code

2Вручную: положить файлы

~/.claude/skills/nextjs/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/nextjs/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о nextjs

Как установить nextjs в Claude Code?

Выполните npx skills add bobmatnyc/claude-mpm-skills --skill nextjs -a claude-code. Файл скилла окажется по пути ~/.claude/skills/nextjs/SKILL.md.

Что делает nextjs?

Это справочник по переменным окружения Next.js: порядок файлов .env*, деление на NEXT_PUBLIC_* и серверные значения, настройка деплоя на Vercel. Отдельной слэш-команды скилл не добавляет.

Нужен ли редеплой после смены NEXT_PUBLIC_*?

Да. Такие переменные попадают в бандл на этапе сборки, поэтому после правки в панели Vercel запустите vercel --prod, иначе браузер получит прежние значения.

Исходный текст

SKILL.md · MIT
---
name: nextjs
description: Next.js environment variable management with file precedence, variable types, and deployment configurations. Use when configuring Next.js applications, managing environment-specific settings, or deploying to Vercel/Railway/Heroku.
user-invocable: false
disable-model-invocation: true
progressive_disclosure:
  entry_point:
    summary: "Next.js environment variable management with file precedence, variable types, and deployment configurations. Use when configuring Next.js applications, managing environment-specific settings, or de..."
    when_to_use: "When working with nextjs-env-variables or related functionality."
    quick_start: "1. Review the core concepts below. 2. Apply patterns to your use case. 3. Follow best practices for implementation."
---
# Next.js Environment Variable Structure

Complete guide to Next.js environment variable management.

## File Structure

```
my-nextjs-app/
├── .env                      # Shared defaults (committed)
├── .env.local               # Local secrets (gitignored)
├── .env.development         # Development defaults (committed)
├── .env.development.local   # Local dev overrides (gitignored)
├── .env.production          # Production defaults (committed)
├── .env.production.local    # Production secrets (gitignored)
├── .env.test                # Test environment (committed)
└── .env.example             # Documentation (committed)
```

## File Precedence

Next.js loads files in this order (higher = higher precedence):

1. `.env.$(NODE_ENV).local` (e.g., `.env.production.local`)
2. `.env.local` (not loaded in test environment)
3. `.env.$(NODE_ENV)` (e.g., `.env.production`)
4. `.env`

**Example**: In production, if `DATABASE_URL` is defined in both `.env` and `.env.production.local`, the value from `.env.production.local` wins.

## Variable Types

### Client-Side Variables (NEXT_PUBLIC_*)

Exposed to the browser. Must prefix with `NEXT_PUBLIC_`.

```bash
# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=UA-123456789
NEXT_PUBLIC_SITE_NAME=My Awesome Site
NEXT_PUBLIC_ENABLE_FEATURE_X=true
```

**Access in code**:
```javascript
// Works in both client and server
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// Usage in components
export default function MyComponent() {
  return <div>API: {process.env.NEXT_PUBLIC_API_URL}</div>;
}
```

**⚠️ Security Warning**: NEVER put secrets in `NEXT_PUBLIC_*` variables!

```bash
# ❌ WRONG - Secret exposed to browser
NEXT_PUBLIC_API_SECRET=sk_live_abc123

# ✅ CORRECT - Secret only on server
API_SECRET=sk_live_abc123
```

### Server-Side Variables

Only available in server-side code (API routes, getServerSideProps, etc.).

```bash
# .env.local
DATABASE_URL=postgres://localhost:5432/mydb
JWT_SECRET=super-secret-jwt-key-do-not-expose
STRIPE_SECRET_KEY=sk_live_abc123
SMTP_PASSWORD=email-password-here
```

**Access in code**:
```javascript
// ✅ Works in API routes
export default async function handler(req, res) {
  const dbUrl = process.env.DATABASE_URL;
  // Use dbUrl...
}

// ✅ Works in getServerSideProps
export async function getServerSideProps() {
  const secret = process.env.JWT_SECRET;
  // Use secret...
}

// ❌ Does NOT work in components (browser)
export default function MyComponent() {
  const dbUrl = process.env.DATABASE_URL; // undefined!
}
```

## Example Files

### .env (Committed - Shared Defaults)

```bash
# Shared defaults for all environments
NEXT_PUBLIC_APP_NAME=My Next.js App
NEXT_PUBLIC_DEFAULT_LOCALE=en

# Database (overridden in .env.local)
DATABASE_URL=postgres://localhost:5432/dev

# External services (no secrets)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_abc123
```

### .env.local (Gitignored - Local Secrets)

```bash
# Local development secrets
DATABASE_URL=postgres://localhost:5432/mylocal
JWT_SECRET=dev-jwt-secret-change-in-production
STRIPE_SECRET_KEY=sk_test_local_key

# Local overrides
NEXT_PUBLIC_API_URL=http://localhost:4000/api
```

### .env.production (Committed - Production Defaults)

```bash
# Production environment defaults
NEXT_PUBLIC_API_URL=https://api.production.com
NEXT_PUBLIC_ANALYTICS_ID=UA-PROD-123456

# These will be overridden by platform env vars
DATABASE_URL=set-this-in-vercel
JWT_SECRET=set-this-in-vercel
```

### .env.example (Committed - Documentation)

```bash
# Copy this to .env.local and fill in actual values

# Client-side (browser accessible)
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=your-analytics-id
NEXT_PUBLIC_SITE_NAME=Your Site Name

# Server-side (secrets)
DATABASE_URL=postgres://user:password@host:5432/database  # pragma: allowlist secret
JWT_SECRET=your-jwt-secret-32-chars-minimum
STRIPE_SECRET_KEY=sk_live_your_stripe_key
SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-smtp-password
```

## Common Patterns

### Database Configuration

```bash
# Development (.env.local)
DATABASE_URL=postgres://localhost:5432/myapp_dev

# Production (Vercel Environment Variables)
DATABASE_URL=postgres://user:pass@prod-host:5432/myapp_prod  # pragma: allowlist secret
```

### API Keys

```bash
# Public keys (client-side)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_abc123

# Secret keys (server-side only)
STRIPE_SECRET_KEY=sk_live_xyz789
```

### Feature Flags

```bash
# Toggle features
NEXT_PUBLIC_ENABLE_DARK_MODE=true
NEXT_PUBLIC_ENABLE_BETA_FEATURES=false
```

## Deployment to Vercel

### Step 1: Add Environment Variables in Vercel

1. Go to Project Settings → Environment Variables
2. Add each variable:
   - **Key**: `DATABASE_URL`
   - **Value**: `postgres://...`
   - **Environments**: Production, Preview, Development

### Step 2: Separate Client vs Server Variables

Vercel automatically exposes `NEXT_PUBLIC_*` variables at build time.

```bash
# Vercel automatically handles:
NEXT_PUBLIC_API_URL=https://api.example.com  # ✅ Exposed to browser

# Server-only:
DATABASE_URL=postgres://...  # ✅ Not exposed to browser
```

### Step 3: Rebuild After Changing NEXT_PUBLIC_ Variables

⚠️ Important: `NEXT_PUBLIC_*` variables are **baked into the build** at build time.

If changing them in Vercel, **redeploy** is required:

```bash
vercel --prod
```

## Validation Workflow

### 1. Validate Local Environment

```bash
# Check structure
python scripts/validate_env.py .env.local --framework nextjs

# Compare with .env.example
python scripts/validate_env.py .env.local --compare-with .env.example

# Check for security issues
python scripts/scan_exposed.py --check-gitignore
```

### 2. Check File Precedence

```bash
# List all .env files
ls -la .env*

# Validate each
for file in .env*; do
  echo "=== $file ==="
  python scripts/validate_env.py $file --framework nextjs
done
```

### 3. Sync to Vercel

```bash
# Compare local vs Vercel
python scripts/sync_secrets.py --platform vercel --compare

# Sync (dry-run first)
python scripts/sync_secrets.py --platform vercel --sync --dry-run

# Actually sync
python scripts/sync_secrets.py --platform vercel --sync --confirm
```

## Common Issues

### Issue: Variable Undefined in Browser

**Symptom**: `process.env.MY_VAR` is `undefined` in component.

**Solution**: Add `NEXT_PUBLIC_` prefix:

```bash
# ❌ Wrong
API_URL=https://api.example.com

# ✅ Correct
NEXT_PUBLIC_API_URL=https://api.example.com
```

### Issue: Changed Variable Not Reflected

**Symptom**: Changed `NEXT_PUBLIC_*` variable in Vercel, but app still uses old value.

**Solution**: Redeploy (variables are baked into build):

```bash
vercel --prod
```

### Issue: Works Locally, Not in Production

**Symptom**: App works with `.env.local`, fails in production.

**Solution**: Ensure all variables from `.env.local` are set in Vercel:

```bash
# Compare
python scripts/sync_secrets.py --platform vercel --compare

# Find missing vars and add them in Vercel UI
```

## Security Checklist

- [ ] `.env.local` in `.gitignore`
- [ ] `.env.*.local` in `.gitignore`
- [ ] No secrets in `NEXT_PUBLIC_*` variables
- [ ] No `.env` files committed with real secrets
- [ ] `.env.example` has structure, not actual values
- [ ] Secrets set directly in Vercel (not in committed files)

## References

- [Next.js Environment Variables Documentation](https://nextjs.org/docs/basic-features/environment-variables)
- [Vercel Environment Variables](https://vercel.com/docs/environment-variables)

---

**Related**: [validation.md](../references/validation.md) | [security.md](../references/security.md) | [frameworks.md](../references/frameworks.md)

## Related Skills

When using Nextjs, these skills enhance your workflow:
- **react**: Core React patterns and hooks for Next.js components
- **tanstack-query**: Server-state management with App Router and Server Components
- **drizzle**: Type-safe ORM for Next.js server actions and API routes
- **prisma**: Alternative ORM with excellent Next.js integration
- **test-driven-development**: Testing Next.js App Router, Server Components, and API routes

[Full documentation available in these skills if deployed in your bundle]

© bobmatnyc · MIT · bobmatnyc/claude-mpm-skills

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →

Сначала — nextjs от других авторов.

nextjs официальный Vercel Labs Помогает разрабатывать и отлаживать приложения на Next.js App Router. Разбирает маршруты, Server Components, загрузку данных и рендеринг. CX Codex GP ChatGPT +1 50установок nextjs pproenca Скилл помогает писать и проверять приложения на Next.js 16 App Router: кэширование, серверные компоненты, маршруты и чистоту кодовой базы. CX Codex +1 1 200установок nextjs PyModel Внедряет стандарты Next.js 16 App Router. Направляет рефакторинг серверных компонентов, кэширования и маршрутов. CX Codex +1 621установок nextjs Claude Skills Maintainers Скилл для работы с Next.js 16, React 19.2 и современными паттернами серверных компонентов, Server Actions и кэширования. Помогает при миграции с версии 15, ошибках async params и настройке Partial Prerendering. CX Codex +1 299установок nextjs ulpi-io Направляет агента при разработке на Next.js App Router с оглядкой на архитектуру проекта, установленную версию фреймворка и общие контракты API. CX Codex +1 182установок vercel-env-sync davila7 Команда vercel-env-sync синхронизирует переменные окружения между локальными файлами .env и проектом на Vercel через Vercel CLI. Помогает выгружать, пушить и проверять секреты. CX Codex +1 406установок vercel-environment-sync davila7 Хук vercel-environment-sync для Claude Code отслеживает изменения .env-файлов и проверяет переменные перед синхронизацией с Vercel. Запускается на каждом сохранении .env-файла через Write, Edit или MultiEdit. 363установок nextjs-on-cloudflare cloudflare Скилл nextjs-on-cloudflare для развёртывания Next.js приложений на Cloudflare Workers через vinext. Используй для новых проектов, миграции существующих приложений или выбора между vinext и OpenNext. CX Codex +1 60 100установок nextjs-deployment giuseppe-trisciuoglio Скилл nextjs-deployment готовит конфигурацию для деплоя Next.js в продакшен. Настраивает многоэтапный Dockerfile, CI/CD через GitHub Actions, мониторинг OpenTelemetry и проверку работоспособности сервиса. CX Codex +1 3 900установок vercel-deployment sickn33 Скилл vercel-deployment для Claude Code добавляет агенту порядок деплоя Next.js-приложений на Vercel. Включается, когда в задаче появляются vercel, deploy, production или переменные окружения. CX Codex +1 1 800установок vercel-deployments devops-skills Скилл vercel-deployments для деплоя фронтенда и фулстек-приложений на Vercel: превью, edge-функции, переменные окружения и защита продакшена. CX Codex +1 351установок

Из того же набора143

Весь набор →
prisma Справочник по Prisma ORM для TypeScript: готовые шаблоны схем, миграции, транзакции и синглтон клиента для Next.js. CX Codex +1 222установок code-quality Скилл code-quality для Claude Code проверяет Python-код на ошибки в исключениях, сравнениях, импортах и локальных переменных. Используется при ревью и самопроверке перед PR. CX Codex +1 221установок react-core Скилл react-core для Claude Code даёт агенту базу по React для работы с компонентами и JSX, пропсами и состоянием, хуками, композицией, списками и контролируемыми полями ввода. CX Codex +1 220установок supabase Скилл учит агента настраивать клиент @supabase/supabase-js, писать запросы к Postgres через PostgREST и реализовывать авторизацию в Next.js, React или Vue. CX Codex +1 219установок tauri Описывает паттерны событий Tauri: двустороннюю коммуникацию, потоки данных и обмен сообщениями между окнами. Показывает работу с real-time обновлениями в настольных приложениях. CX Codex +1 210установок react-advanced Скилл react-advanced для Claude Code задаёт правила работы с React 19: внедрение React Compiler, Actions, конкурентный рендеринг и отказ от лишнего useMemo. CX Codex +1 209установок react-hooks-composition Скилл react-hooks-composition для Claude Code помогает собирать React-хуки для загрузки данных, поиска с задержкой и контекстов. Связывает состояние интерфейса с запросами к API. CX Codex +1 206установок code-quality-scoring Скилл code-quality-scoring для Claude Code оценивает здоровье кодовой базы, техдолг и готовность к облаку. Оценивает проект целиком перед рефакторингом. CX Codex +1 206установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой