Cursor .mdc para Next.js 15: una regla que mantiene el límite entre los componentes del servidor y del cliente
Donde el agente rompe el App Router
Escenario típico: pídale al Cursor que "agregue un botón Me gusta a la página del artículo". El agente ve que se necesita useState y coloca "use client" en la parte superior app/blog/[slug]/page.tsx. La página se compila, pero ahora todo su código, incluido el marcado del artículo, pasa al paquete del cliente y la consulta a la base de datos dentro de la página deja de funcionar. El segundo escenario común: el agente importa lib/db.ts al componente del cliente por un tipo y el ensamblado falla o, peor aún, un módulo con variables de entorno termina en el paquete.
El modelo no conoce sus acuerdos de límites entre el servidor y el cliente. Deben escribirse explícitamente en la regla que el Cursor sustituye cuando se trabaja con archivos de App Router.
Regla completa
Crea un archivo .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".El campo globs limita la aplicación de la regla a App Router y archivos de biblioteca, por lo que no contamina el contexto cuando el agente edita, por ejemplo, scripts de implementación. alwaysApply: false significa que la regla está conectada mediante archivos coincidentes y no en cada solicitud.
Apoyar la regla con código
Una regla es una sugerencia modelo, no una prueba. Para detectar el error en la compilación, instale el paquete 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 });Si el módulo cliente importa incluso transitivamente lib/db.ts, next build se detendrá con un error comprensible. Para el caso contrario, existe el paquete client-only: se utiliza para marcar el código que toca window o localStorage.
Patrón de referencia para el agente.
Es útil poner un breve ejemplo en la regla o al lado de ella que seguirá el agente:
// 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]);
}El sufijo .client.tsx no es un requisito de Next.js, sino una convención. Pero les permite a usted y al agente entender por el nombre del archivo dónde está el borde.
Cómo reconocer una infracción
- Error de compilación que indica que el enlace solo funciona en el componente cliente: el enlace se llama en un archivo sin
"use client". La respuesta correcta es eliminar la parte interactiva en lugar de marcar todo el elemento principal. - Error que indica que las funciones no se pueden pasar a los componentes del cliente a menos que estén marcadas con
"use server"- el agente pasó un controlador del componente del servidor. Realice una acción del servidor o mueva el controlador dentro del componente del cliente. - Una advertencia de hidratación a menudo significa que la salida del servidor utiliza valores dependientes de
Date.now(),Math.random()owindow. - Paquete de cliente sospechosamente grande: ejecute
ANALYZE=truecon@next/bundle-analyzery verifique si contiene algún analizador de rebajas o SDK que solo deba vivir en el servidor.
Cuando esta regla es redundante
Si el proyecto está completamente en Pages Router o es un SPA en Vite, la regla es inútil y solo desperdicia contexto. Para un prototipo pequeño con dos páginas y sin base, una línea de las reglas generales es suficiente. Y recuerde: .mdc reduce la tasa de error del agente, pero no reemplaza a server-only y la revisión de diferencias.