v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T09:01:00.000Z▲ 0 upvotes

Cursor .mdc para Next.js 15: una regla que mantiene el límite entre los componentes del servidor y del cliente

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

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() o window.
  • Paquete de cliente sospechosamente grande: ejecute ANALYZE=true con @next/bundle-analyzer y 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.

Обсуждение (0)

Ещё на vbcd4u.com