Шпаргалка по основным моментам «next.js»

# Проект
npm install
npm run dev
npm run build && npm run start
npm run lint
npm run test

# Prisma
npm run db:migrate          # dev: новая миграция + apply
npm run db:migrate:deploy   # prod/CI: только apply
npm run db:push             # прототип без файла миграции
npm run db:generate         # обновить клиент
npm run db:seed             # тестовые данные
npm run db:studio           # GUI

src/app/
├── layout.tsx              # корневой layout (HTML, шрифты, глобальные стили)
├── (public)/               # route group — не влияет на URL
│   ├── layout.tsx
│   ├── page.tsx            # GET /
│   └── watch/[slug]/
│       └── page.tsx        # GET /watch/:slug
├── (admin)/
│   └── admin/
│       ├── layout.tsx
│       └── videos/
│           └── page.tsx    # GET /admin/videos
└── api/
    └── videos/
        └── route.ts        # GET/POST /api/videos

// src/app/(public)/page.tsx — Server Component
import { listPublishedVideos } from "@/lib/queries/videos";

export default async function HomePage() {
  const videos = await listPublishedVideos(); // запрос к Prisma на сервере
  return (/* ... */);
}

"use client";

import { useState } from "react";

export function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

// src/app/api/videos/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET() {
  const videos = await listPublishedVideos();
  return NextResponse.json({ videos });
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  // валидация, запись в БД...
  return NextResponse.json({ ok: true }, { status: 201 });
}

export default async function WatchPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  // ...
}

npx create-next-app@latest my-app

my-app/
├── prisma/
│   ├── schema.prisma
│   ├── migrations/
│   └── seed.ts
├── src/
│   ├── app/           # страницы и API
│   ├── components/    # UI-компоненты
│   └── lib/           # утилиты, Prisma-клиент, запросы к БД
├── public/            # статика (favicon, robots.txt)
├── .env               # локальные секреты (не коммитить!)
├── .env.example       # шаблон переменных для команды
├── next.config.ts
├── package.json
└── docker-compose.yml # PostgreSQL и прочие сервисы

npm install @prisma/client
npm install -D prisma
npx prisma init

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

{
  "scripts": {
    "dev": "next dev",
    "build": "prisma generate && next build",
    "start": "next start",
    "lint": "eslint",
    "test": "vitest run",
    "db:generate": "prisma generate",
    "db:migrate": "prisma migrate dev",
    "db:migrate:deploy": "prisma migrate deploy",
    "db:push": "prisma db push",
    "db:seed": "prisma db seed",
    "db:studio": "prisma studio"
  }
}

npm install
npm run db:migrate    # создать таблицы
npm run db:seed       # опционально: тестовые данные
npm run dev           # http://localhost:3000

// src/lib/prisma.ts
import { PrismaClient } from "@prisma/client";

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

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === "development" ? ["error", "warn"] : ["error"],
  });

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

model Video {
  id        String   @id @default(uuid())
  title     String
  slug      String   @unique
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

npm run db:migrate
# Prisma спросит имя миграции, например: add_video_table

import { prisma } from "@/lib/prisma";

const video = await prisma.video.create({
  data: { title: "Demo", slug: "demo" },
});

npx prisma migrate deploy
npx prisma generate
npm run build

{
  "prisma": {
    "seed": "tsx prisma/seed.ts"
  }
}

npm run db:seed

┌─────────────────────────────────────────┐
│  src/app/          страницы, layouts    │
│  src/components/   переиспользуемый UI  │
├─────────────────────────────────────────┤
│  src/lib/queries/  доступ к данным      │
│  src/lib/          prisma, s3, валидация│
├─────────────────────────────────────────┤
│  Prisma --> PostgreSQL                  │
│  S3/MinIO, Redis, Worker (вне Next.js)  │
└─────────────────────────────────────────┘

const parsed = createVideoSchema.safeParse(body);
if (!parsed.success) {
  return validationError(parsed.error);
}

import { prisma } from "@/lib/prisma";
import { VideoCard } from "@/components/video/video-card";

Browser (форма)
    ↓  FormData
Server Action (actions.ts)
    ↓  Zod safeParse
prisma.video.create()
    ↓
PostgreSQL

src/
├── app/
│   └── videos/
│       ├── actions.ts          # Server Action
│       └── new/
│           └── page.tsx        # страница /videos/new
├── components/
│   └── create-video-form.tsx   # Client Component с <form>
└── lib/
    ├── prisma.ts
    └── validations/
        └── video.ts            # Zod-схема

import { z } from "zod";

export const createVideoSchema = z.object({
  title: z.string().trim().min(1, "Введите название").max(200),
  slug: z
    .string()
    .trim()
    .min(1, "Введите slug")
    .max(200)
    .regex(/^[a-z0-9-]+$/, "Только латиница, цифры и дефис"),
});

export type VideoFormState = {
  error?: string;
  fieldErrors?: Record<string, string[]>;
};

"use server";

import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";

import { prisma } from "@/lib/prisma";
import { createVideoSchema, type VideoFormState } from "@/lib/validations/video";

export async function createVideoAction(
  _prev: VideoFormState,
  formData: FormData,
): Promise<VideoFormState> {
  const parsed = createVideoSchema.safeParse({
    title: formData.get("title"),
    slug: formData.get("slug"),
  });

  if (!parsed.success) {
    return { fieldErrors: parsed.error.flatten().fieldErrors };
  }

  try {
    await prisma.video.create({ data: parsed.data });
  } catch {
    return { error: "Видео с таким slug уже существует" };
  }

  revalidatePath("/videos");
  redirect("/videos");
}

"use client";

import { useActionState } from "react";

import { createVideoAction } from "@/app/videos/actions";
import type { VideoFormState } from "@/lib/validations/video";

const initialState: VideoFormState = {};

export function CreateVideoForm() {
  const [state, formAction, pending] = useActionState(createVideoAction, initialState);

  return (
    <form action={formAction} className="space-y-4">
      <div>
        <label htmlFor="title" className="mb-1 block text-sm font-medium">
          Название
        </label>
        <input
          id="title"
          name="title"
          required
          className="min-h-11 w-full rounded-lg border px-3"
        />
        {state.fieldErrors?.title ? (
          <p className="mt-1 text-sm text-red-600">{state.fieldErrors.title[0]}</p>
        ) : null}
      </div>

      <div>
        <label htmlFor="slug" className="mb-1 block text-sm font-medium">
          Slug
        </label>
        <input
          id="slug"
          name="slug"
          required
          placeholder="my-video"
          className="min-h-11 w-full rounded-lg border px-3"
        />
        {state.fieldErrors?.slug ? (
          <p className="mt-1 text-sm text-red-600">{state.fieldErrors.slug[0]}</p>
        ) : null}
      </div>

      <button type="submit" disabled={pending} className="rounded-lg bg-black px-4 py-2 text-white">
        {pending ? "Сохранение…" : "Создать"}
      </button>

      {state.error ? (
        <p className="text-sm text-red-600" role="alert">
          {state.error}
        </p>
      ) : null}
    </form>
  );
}

import { CreateVideoForm } from "@/components/create-video-form";

export default function NewVideoPage() {
  return (
    <main className="mx-auto max-w-lg p-8">
      <h1 className="text-2xl font-bold">Новое видео</h1>
      <div className="mt-6">
        <CreateVideoForm />
      </div>
    </main>
  );
}

npm run dev

npm run lint

npm run test              # unit-тесты (Vitest)
npm run test:integration  # интеграционные (video-platform)

npm run db:studio

npm run build
npm run start