Cursor .mdc para Next.js 15: uma regra que mantém a fronteira entre os componentes servidor e cliente
Onde o agente quebra o App Router
Cenário típico: peça ao Cursor para “adicionar um botão curtir à página do artigo”. O agente vê que useState é necessário e coloca "use client" no topo app/blog/[slug]/page.tsx. A página compila, mas agora todo o seu código, incluindo a marcação do artigo, vai para o pacote do cliente e a consulta ao banco de dados dentro da página para de funcionar. O segundo cenário comum: o agente importa lib/db.ts para o componente cliente por causa de um tipo, e o assembly trava ou, pior, um módulo com variáveis de ambiente acaba no pacote.
O modelo não conhece seus acordos de limite entre o servidor e o cliente. Eles precisam ser escritos explicitamente na regra que o Cursor substitui ao trabalhar com arquivos do App Router.
Regra inteira
Crie um arquivo .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".O campo globs limita a aplicação da regra ao App Router e arquivos de biblioteca, para não poluir o contexto quando o agente edita, por exemplo, scripts de implantação. alwaysApply: false significa que a regra está conectada por arquivos correspondentes, e não em todas as solicitações.
Apoie a regra com código
Uma regra é uma dica de modelo, não um teste. Para detectar o erro na compilação, instale o pacote 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 });Se o módulo cliente importar transitivamente lib/db.ts, next build irá parar com um erro compreensível. Para o caso oposto, existe o pacote client-only: ele é usado para marcar o código que toca em window ou localStorage.
Padrão de referência para o agente
É útil colocar um pequeno exemplo na regra ou próximo a ela que o agente irá seguir:
// 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]);
}O sufixo .client.tsx não é um requisito do Next.js, mas uma convenção. Mas permite que você e o agente entendam pelo nome do arquivo onde fica a borda.
Como reconhecer uma violação
- Erro de build informando que o hook só funciona no Componente Cliente significa: o hook é chamado em um arquivo sem
"use client". A resposta correta é retirar a parte interativa em vez de sinalizar todo o pai. - Erro que as funções não podem ser passadas para os componentes do cliente, a menos que estejam marcadas com
"use server"- o agente passou um manipulador do componente do servidor. Execute uma ação do servidor ou mova o manipulador dentro do componente cliente. - Um aviso de hidratação geralmente significa que a saída do servidor usa valores dependentes de
Date.now(),Math.random()ouwindow. - Pacote de cliente suspeitamente grande: execute
ANALYZE=truecom@next/bundle-analyzere verifique se ele contém algum analisador de markdown ou SDKs que deveria residir apenas no servidor.
Quando esta regra é redundante
Se o projeto for inteiramente no Pages Router ou for um SPA no Vite, a regra é inútil e só desperdiça contexto. Para um protótipo pequeno com duas páginas e sem base, basta uma linha nas regras gerais. E lembre-se: .mdc reduz a taxa de erro do agente, mas não substitui server-only e revisão de diferenças.