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 і рев'ю диффа.