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

vercel-reference-architecture — скилл для Claude Code: установка

Скилл vercel-reference-architecture разворачивает эталонную архитектуру для Next.js на Vercel. Помогает настроить слои edge и serverless, структурировать API и защитить роуты.

MIT 1 установок ★ 2 935 обновлён 2026-11-01

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

Что делает vercel-reference-architecture

Скилл задаёт типовую структуру для Next.js 14+. Внутри описано чёткое деление проекта: страницы App Router, клиенты баз данных и Edge Middleware. Агент работает с проектом через инструменты Read, Write, Edit и Grep.

Архитектура опирается на валидацию переменных окружения через Zod в src/lib/env.ts и ленивую инициализацию PrismaClient в src/lib/db.ts. Ошибки конфигурации ловятся сразу при запуске. Для авторизации используется middleware.ts с проверкой сессионных кук, а для мониторинга базы — динамический эндпоинт /api/health.

Шаблон жёстко ориентирован на TypeScript, Prisma и Zod. При другом стеке код придётся адаптировать.

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

  • разложить проект Next.js по слоям edge и serverless
  • валидировать переменные окружения через Zod при старте приложения
  • предотвратить дублирование подключений Prisma в режиме горячей перезагрузки
  • настроить Edge Middleware для ограничения доступа к защищённым разделам

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

  • Разверни файловую структуру проекта Vercel на Next.js App Router
  • Создай валидацию переменных окружения в src/lib/env.ts через Zod
  • Настрой edge middleware для проверки сессионной куки в защищённых роутах

Как установить vercel-reference-architecture

1Через Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-reference-architecture -a claude-code

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

~/.claude/skills/vercel-reference-architecture/SKILL.md

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

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

Вопросы о vercel-reference-architecture

Как установить vercel-reference-architecture в Claude Code?

Выполните команду npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-reference-architecture -a claude-code. Конфигурация запишется в файл ~/.claude/skills/vercel-reference-architecture/SKILL.md.

Для чего нужен этот скилл?

Он помогает агенту организовать архитектуру приложений на Vercel по единому стандарту. Скилл задаёт структуру папок, правила кэширования API-роутов и заголовки безопасности в vercel.json.

Какие зависимости нужны для шаблона?

Понадобятся TypeScript и Next.js версии 14 или выше. Примеры кода из скилла рассчитаны на работу с библиотеками Prisma и Zod.

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

SKILL.md · MIT
---
name: vercel-reference-architecture
description: 'Implement a Vercel reference architecture with layered project structure
  and best practices.

  Use when designing new Vercel projects, reviewing project structure,

  or establishing architecture standards for Vercel applications.

  Trigger with phrases like "vercel architecture", "vercel project structure",

  "vercel best practices layout", "how to organize vercel project".

  '
allowed-tools: Read, Write, Edit, Grep
version: 1.18.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- vercel
- architecture
- best-practices
compatibility: Designed for Claude Code
---
# Vercel Reference Architecture

## Overview

Implement a production-ready Vercel project architecture with clear separation across edge, server, and client layers. Covers directory structure, middleware patterns, API route organization, shared utilities, and configuration management.

## Prerequisites

- Understanding of Vercel's deployment model (edge, serverless, static)
- TypeScript project setup
- Next.js 14+ (recommended) or other Vercel-supported framework

## Instructions

### Step 1: Directory Structure

```
my-vercel-app/
├── public/                    # Static assets (served from CDN)
│   ├── favicon.ico
│   └── images/
├── src/
│   ├── app/                   # Next.js App Router pages
│   │   ├── layout.tsx         # Root layout
│   │   ├── page.tsx           # Home page
│   │   ├── api/               # API routes (serverless functions)
│   │   │   ├── health/route.ts
│   │   │   ├── users/route.ts
│   │   │   └── webhooks/
│   │   │       └── vercel/route.ts
│   │   ├── dashboard/         # Protected pages
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx
│   │   └── (marketing)/       # Public pages (route group)
│   │       ├── pricing/page.tsx
│   │       └── about/page.tsx
│   ├── lib/                   # Shared utilities (server + client)
│   │   ├── api-client.ts      # External API wrapper
│   │   ├── db.ts              # Database client (lazy singleton)
│   │   ├── env.ts             # Typed environment variables
│   │   └── errors.ts          # Error classes
│   ├── components/            # React components
│   │   ├── ui/                # Design system primitives
│   │   └── features/          # Feature-specific components
│   └── middleware.ts          # Edge Middleware (auth, redirects)
├── vercel.json                # Vercel configuration
├── next.config.js             # Next.js configuration
├── tsconfig.json
├── package.json
└── .env.example               # Required env vars (no values)
```

### Step 2: Typed Environment Variables

```typescript
// src/lib/env.ts — validate env vars at import time
import { z } from 'zod';

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  API_SECRET: z.string().min(16),
  NEXT_PUBLIC_API_URL: z.string().url(),
  VERCEL_ENV: z.enum(['production', 'preview', 'development']).default('development'),
  VERCEL_URL: z.string().optional(),
});

// Fails fast at startup if env vars are missing
export const env = envSchema.parse(process.env);

// Type-safe access throughout the app
// Usage: import { env } from '@/lib/env'; env.DATABASE_URL
```

### Step 3: Database Client (Lazy Singleton)

```typescript
// src/lib/db.ts — lazy init to minimize cold starts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined };

export const db = globalForPrisma.prisma ?? new PrismaClient({
  log: process.env.VERCEL_ENV === 'development' ? ['query'] : ['error'],
});

// Prevent multiple instances in development (hot reload)
if (process.env.VERCEL_ENV !== 'production') {
  globalForPrisma.prisma = db;
}
```

### Step 4: API Route Pattern

```typescript
// src/app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { db } from '@/lib/db';
import { env } from '@/lib/env';

export async function GET(request: NextRequest) {
  try {
    const searchParams = request.nextUrl.searchParams;
    const limit = Number(searchParams.get('limit') ?? 20);

    const users = await db.user.findMany({ take: limit });
    return NextResponse.json({ users }, {
      headers: { 'Cache-Control': 's-maxage=60, stale-while-revalidate=300' },
    });
  } catch (error) {
    console.error('GET /api/users failed:', error);
    return NextResponse.json(
      { error: 'Internal server error', requestId: crypto.randomUUID() },
      { status: 500 }
    );
  }
}

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const user = await db.user.create({ data: body });
    return NextResponse.json({ user }, { status: 201 });
  } catch (error) {
    console.error('POST /api/users failed:', error);
    return NextResponse.json(
      { error: 'Failed to create user' },
      { status: 400 }
    );
  }
}
```

### Step 5: Edge Middleware for Auth

```typescript
// src/middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Skip auth for public routes
  if (pathname.startsWith('/api/health') || pathname.startsWith('/api/webhooks')) {
    return NextResponse.next();
  }

  // Check auth for dashboard routes
  if (pathname.startsWith('/dashboard') || pathname.startsWith('/api/')) {
    const token = request.cookies.get('session')?.value;
    if (!token) {
      if (pathname.startsWith('/api/')) {
        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
      }
      return NextResponse.redirect(new URL('/login', request.url));
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

### Step 6: Health Check Endpoint

```typescript
// src/app/api/health/route.ts
import { db } from '@/lib/db';

export const dynamic = 'force-dynamic'; // Never cache health checks

export async function GET() {
  const checks: Record<string, 'ok' | 'error'> = {};

  // Database connectivity
  try {
    await db.$queryRaw`SELECT 1`;
    checks.database = 'ok';
  } catch {
    checks.database = 'error';
  }

  const allHealthy = Object.values(checks).every(v => v === 'ok');

  return Response.json({
    status: allHealthy ? 'healthy' : 'degraded',
    checks,
    version: process.env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7) ?? 'local',
    region: process.env.VERCEL_REGION ?? 'local',
    timestamp: new Date().toISOString(),
  }, {
    status: allHealthy ? 200 : 503,
  });
}
```

### Step 7: Vercel Configuration

```json
// vercel.json
{
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ],
  "rewrites": [
    { "source": "/docs/:path*", "destination": "https://docs.example.com/:path*" }
  ],
  "redirects": [
    { "source": "/old-page", "destination": "/new-page", "permanent": true }
  ]
}
```

## Layer Responsibilities

| Layer | Runtime | Responsibilities |
|-------|---------|-----------------|
| Edge (middleware.ts) | V8 isolates | Auth, redirects, A/B testing, headers |
| Server (api routes) | Node.js | Database queries, business logic, webhooks |
| Static (pages) | CDN | Pre-rendered pages, ISR, images |
| Client (components) | Browser | Interactivity, client state |

## Output

- Layered project structure with clear separation of concerns
- Typed environment variables validated at startup
- Lazy-initialized database client minimizing cold starts
- Edge Middleware handling authentication before server layer
- Health check endpoint for deployment verification

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| Env validation fails on deploy | Missing required variable | Add to Vercel dashboard for target environment |
| Middleware runs on static assets | Matcher too broad | Add exclusions for `_next/static`, `_next/image` |
| Database connection pool exhausted | Too many concurrent functions | Use connection pooler (PgBouncer, Prisma Accelerate) |
| API route not found | Wrong directory structure | Must be in `src/app/api/` with `route.ts` filename |

## Examples

### Validate the layer boundary before production traffic

Implement edge middleware only for routing and authorization decisions, keep database access inside server routes, and expose a non-sensitive health endpoint that verifies dependency reachability without returning credentials. Deploy the architecture to preview, test static, edge, and server paths with synthetic identities, and measure middleware overhead. Preserve the prior deployment as rollback until observability confirms the new path is stable under normal traffic.

## Resources

- [Next.js Project Structure](https://nextjs.org/docs/getting-started/project-structure)
- [Vercel Project Configuration](https://vercel.com/docs/project-configuration)
- [Middleware Documentation](https://vercel.com/docs/functions/edge-middleware)
- [API Routes (App Router)](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)

## Next Steps

For multi-environment setup, see `vercel-multi-env-setup`.

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

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

Все скиллы по теме «Облака: AWS, Azure, GCP» →
vercel-development Mindrally Скилл vercel-development для Claude Code: правила кода под Next.js App Router, React Server Components и Vercel AI SDK. Не даёт агенту писать клиентские компоненты там, где хватило бы серверных. CX Codex +1 756установок vercel-edge-function davila7 Команда Claude Code создаёт заготовку Vercel Edge Function с обработчиками GET и POST, примерами геолокации и JWT-аутентификации для интеграции в Next.js-проект. CX Codex +1 364установок nextjs-vercel-typescript-cursorrules-prompt-file PatrickJS Правило nextjs-vercel-typescript-cursorrules-prompt-file для Cursor, которое задаёт стиль кода и структуру проекта на Next.js с TypeScript, Vercel middleware и KV-базой. CX Codex +1 ★ 41 178звёзд репо 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установок vercel-deploy-optimize davila7 Команда vercel-deploy-optimize для Claude Code, которая оптимизирует и разворачивает Next.js-приложение на Vercel с мониторингом производительности. CX Codex +1 506установок

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

Весь набор →
customerio-cost-tuning Скилл customerio-cost-tuning ищет переплату в Customer.io: лишние профили, неактивные аккаунты, дубли событий. Показывает, что можно убрать, не тронув доставку. CX Codex +1 1установок apollo-core-workflow-a Скилл apollo-core-workflow-a настраивает пайплайн лидогенерации через Apollo.io: ищет компании и контакты, а затем обогащает выбранные лиды телефонами и почтой. CX Codex +1 1установок firecrawl-migration-deep-dive Скилл firecrawl-migration-deep-dive помогает заменить Puppeteer, Playwright, Cheerio или другой скрейпер на Firecrawl v2 с проверкой паритета, политик, стоимости и отката. CX Codex +1 1установок vercel-webhooks-events Скилл vercel-webhooks-events для Claude Code, Codex, Cursor и других платформ обрабатывает события развёртывания Vercel с проверкой подписи HMAC. CX Codex +1 1установок vercel-policy-guardrails Скилл vercel-policy-guardrails добавляет проверки для Vercel-проектов: ESLint-правила, поиск секретов, CI-проверки и контроль защищённых маршрутов. CX Codex +1 1установок gcs-lifecycle-policy Скилл gcs-lifecycle-policy для работы с политиками жизненного цикла в Google Cloud Storage. Включается сам, когда в запросе упоминается gcs или lifecycle policy. CX Codex +1 1установок gcs-bucket-config Скилл gcs-bucket-config настраивает бакеты Google Cloud Storage через CLI и генерирует конфигурации. Срабатывает в Claude Code при упоминании GCS и команд gcloud. CX Codex +1 1установок s3-bucket-policy-generator Скилл s3-bucket-policy-generator помогает разбирать задачи генерации политик для S3, создавать конфигурации и проверять их по распространённым требованиям. CX Codex +1 1установок

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

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