Cursor .mdc для Next.js 15: правило, которое держит границу Server и Client Components
Где агент ломает 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 и ИИ-агентов под ключ.