Kursor .mdc dla Next.js 15: reguła utrzymująca granicę pomiędzy komponentami serwera i klienta
Gdzie agent psuje router aplikacji
Typowy scenariusz: poproś Cursora o „dodanie przycisku Lubię to do strony artykułu”. Agent widzi, że potrzebny jest useState i umieszcza "use client" na samej górze app/blog/[slug]/page.tsx. Strona się kompiluje, ale teraz cały jej kod, łącznie ze znacznikami artykułu, trafia do pakietu klienta, a zapytanie do bazy danych wewnątrz strony przestaje działać. Drugi częsty scenariusz: agent importuje lib/db.ts do komponentu klienta ze względu na jeden typ, a montaż ulega awarii lub, co gorsza, moduł ze zmiennymi środowiskowymi ląduje w pakiecie.
Model nie zna ustaleń granicznych między serwerem a klientem. Muszą być jawnie zapisane w regule, którą Cursor zastępuje podczas pracy z plikami App Router.
Cała reguła
Utwórz plik .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".Pole globs ogranicza zastosowanie reguły do routera aplikacji i plików bibliotek, dzięki czemu nie zanieczyszcza kontekstu, gdy agent edytuje na przykład skrypty wdrażania. alwaysApply: false oznacza, że reguła jest łączona poprzez pasujące pliki, a nie w każdym żądaniu.
Wesprzyj regułę kodem
Reguła jest wskazówką modelową, a nie testem. Aby wyłapać błąd w kompilacji, zainstaluj pakiet server-only:
[[VB_1_KOD]]
// lib/db.ts
import "server-only";
import { Pool } from "pg";
export const pool = new Pool({ connectionString: process.env.DATABASE_URL });Jeśli moduł klienta nawet przechodniowo zaimportuje lib/db.ts, next build zatrzyma się ze zrozumiałym błędem. W odwrotnym przypadku istnieje pakiet client-only: służy do oznaczenia kodu, który dotyka window lub localStorage.
Wzorzec odniesienia dla agenta
Przydatne jest umieszczenie w regule lub obok niej krótkiego przykładu, którym będzie się kierował agent:
// 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>
);
}[[VB_4_KOD]]
[[VB_5_KOD]]
Sufiks .client.tsx nie jest wymaganiem Next.js, ale konwencją. Ale pozwala zarówno Tobie, jak i agentowi zrozumieć po nazwie pliku, gdzie znajduje się granica.
Jak rozpoznać naruszenie
- Błąd kompilacji stwierdzający, że hook działa tylko w komponencie klienta, oznacza: hook jest wywoływany w pliku bez
"use client". Prawidłową reakcją jest usunięcie części interaktywnej, zamiast oflagowania całego elementu nadrzędnego. - Błąd uniemożliwiający przekazanie funkcji do Komponentów Klienta, chyba że są one oznaczone
"use server"- agent przekazał procedurę obsługi z komponentu serwera. Wykonaj akcję serwera lub przenieś moduł obsługi do komponentu klienta. - Ostrzeżenie o nawodnieniu często oznacza, że dane wyjściowe serwera używają wartości zależnych od
Date.now(),Math.random()lubwindow. - Podejrzanie duży pakiet klienta: uruchom
ANALYZE=truez@next/bundle-analyzeri sprawdź, czy zawiera jakieś parsery przecen lub pakiety SDK, które powinny znajdować się tylko na serwerze.
Gdy ta reguła jest zbędna
Jeśli projekt jest w całości na Pages Router lub jest SPA na Vite, reguła jest bezużyteczna i marnuje tylko kontekst. W przypadku małego prototypu składającego się z dwóch stron i pozbawionego podstawy wystarczy jedna linijka zasad ogólnych. I pamiętaj: .mdc zmniejsza współczynnik błędów agenta, ale nie zastępuje server-only i przeglądu różnicowego.