v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T09:01:00.000Z▲ 0 upvotes

Cursor .mdc для Next.js 15: правило, которое держит границу Server и Client Components

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

Где агент ломает App Router

Типичный сценарий: просите Cursor «добавить кнопку лайка на страницу статьи». Агент видит, что нужен useState, и ставит "use client" в самый верх app/blog/[slug]/page.tsx. Страница компилируется, но теперь весь её код, включая разметку статьи, уходит в клиентский бандл, а запрос к базе внутри страницы перестаёт работать. Второй частый вариант: агент импортирует lib/db.ts в клиентский компонент ради одного типа, и сборка падает или, хуже, в бандл попадает модуль с переменными окружения.

Модель не знает ваших соглашений о границе между сервером и клиентом. Их нужно записать явно в правило, которое Cursor подставляет при работе с файлами App Router.

Правило целиком

Создайте файл .cursor/rules/next-server-client.mdc:

---
description: Границы Server/Client Components в Next.js 15 App Router
globs: app/**/*.tsx, app/**/*.ts, components/**/*.tsx, lib/**/*.ts
alwaysApply: false
---

# Server и Client Components

- По умолчанию каждый компонент в app/ — Server Component. Не добавляй "use client" без причины.
- "use client" ставится только в листовой интерактивный компонент (кнопка, форма, виджет),
  никогда в page.tsx, layout.tsx, template.tsx.
- Если нужен хук (useState, useEffect, useRouter из next/navigation) — вынеси интерактивную часть
  в отдельный файл components/<feature>/<Name>.client.tsx и импортируй его из серверного компонента.
- Пропсы из Server в Client Component должны быть сериализуемыми: строки, числа, boolean, null,
  массивы, простые объекты, Date. Нельзя передавать функции, классы, экземпляры Map/Set с методами,
  ORM-модели. Исключение — Server Actions (функции из файла с "use server").
- Модули с доступом к БД, секретам и файловой системе начинаются с `import "server-only";`.
- В Next.js 15 params и searchParams в page/layout — Promise: `const { slug } = await params;`.
  cookies(), headers(), draftMode() — асинхронные, вызывай через await.
- Переменные окружения без префикса NEXT_PUBLIC_ доступны только на сервере. Не читай
  process.env.SECRET в файлах с "use client".
- Серверный компонент можно передать в клиентский через children или другой проп-слот,
  но нельзя импортировать серверный компонент внутри файла с "use client".

Поле globs ограничивает применение правила файлами App Router и библиотек, поэтому оно не засоряет контекст, когда агент правит, например, скрипты деплоя. alwaysApply: false означает, что правило подключается по совпадению файлов, а не в каждый запрос.

Подкрепите правило кодом

Правило — это подсказка модели, а не проверка. Чтобы ошибка ловилась сборкой, установите пакет server-only:

npm install server-only
// lib/db.ts
import "server-only";
import { Pool } from "pg";

export const pool = new Pool({ connectionString: process.env.DATABASE_URL });

Если клиентский модуль хотя бы транзитивно импортирует lib/db.ts, next build остановится с понятной ошибкой. Для обратного случая есть пакет client-only: им помечают код, который трогает window или localStorage.

Эталонный паттерн для агента

Полезно положить в правило или рядом короткий пример, на который агент будет равняться:

// app/blog/[slug]/page.tsx — Server Component
import { getPost } from "@/lib/posts";
import { LikeButton } from "@/components/blog/LikeButton.client";

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.html }} />
      <LikeButton postId={post.id} initialCount={post.likes} />
    </article>
  );
}
// components/blog/LikeButton.client.tsx
"use client";
import { useOptimistic, useTransition } from "react";
import { likePost } from "@/app/actions/like";

export function LikeButton({ postId, initialCount }: { postId: string; initialCount: number }) {
  const [count, addLike] = useOptimistic(initialCount, (c: number) => c + 1);
  const [pending, startTransition] = useTransition();

  return (
    <button
      disabled={pending}
      onClick={() =>
        startTransition(async () => {
          addLike(null);
          await likePost(postId);
        })
      }
    >
      ♥ {count}
    </button>
  );
}
// app/actions/like.ts
"use server";
import { pool } from "@/lib/db";

export async function likePost(postId: string) {
  await pool.query("UPDATE posts SET likes = likes + 1 WHERE id = $1", [postId]);
}

Суффикс .client.tsx — не требование Next.js, а соглашение. Зато оно позволяет и вам, и агенту по имени файла понять, где проходит граница.

Как распознать нарушение

  • Ошибка сборки про то, что хук работает только в Client Component, означает: хук вызван в файле без "use client". Правильная реакция — вынести интерактивную часть, а не помечать весь родитель.
  • Ошибка о том, что функции нельзя передавать в Client Components, если они не помечены "use server", — агент передал обработчик из серверного компонента. Либо делайте Server Action, либо переносите обработчик внутрь клиентского компонента.
  • Предупреждение о гидратации часто означает, что в серверном выводе использованы Date.now(), Math.random() или window-зависимые значения.
  • Подозрительно большой клиентский бандл: запустите ANALYZE=true с @next/bundle-analyzer и проверьте, не попали ли в него markdown-парсеры или SDK, которые должны жить только на сервере.

Когда это правило избыточно

Если проект целиком на Pages Router или это SPA на Vite, правило бесполезно и только тратит контекст. Для маленького прототипа, где две страницы и нет базы, достаточно одной строки в общих правилах. И помните: .mdc снижает частоту ошибок агента, но не заменяет server-only и ревью диффа.

Нужна реализация под ваш проект или аудит архитектуры?

Разрабатываем сайты на Next.js, Telegram-ботов, интеграции с CRM и ИИ-агентов под ключ.

Обсуждение (0)

Ещё на vbcd4u.com