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: uma regra que mantém a fronteira entre os componentes servidor e cliente

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

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() ou window.
  • Pacote de cliente suspeitamente grande: execute ANALYZE=true com @next/bundle-analyzer e 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.

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

Ещё на vbcd4u.com