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

Cursor .mdc voor Next.js 15: een regel die de grens tussen server- en clientcomponenten bewaakt

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

Waar de agent de app-router verbreekt

Typisch scenario: vraag Cursor om “een like-knop toe te voegen aan de artikelpagina.” De agent ziet dat useState nodig is en plaatst "use client" helemaal bovenaan app/blog/[slug]/page.tsx. De pagina wordt gecompileerd, maar nu gaat alle code, inclusief de artikelopmaak, naar de clientbundel en werkt de zoekopdracht naar de database op de pagina niet meer. Het tweede veelvoorkomende scenario: de agent importeert lib/db.ts in de clientcomponent omwille van één type, en de assembly crasht of, erger nog, een module met omgevingsvariabelen komt in de bundel terecht.

Het model kent uw grensafspraken tussen de server en de client niet. Ze moeten expliciet worden geschreven in de regel die Cursor vervangt bij het werken met App Router-bestanden.

Volledige regel

Maak een bestand .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".

Het veld globs beperkt de toepassing van de regel op App Router- en bibliotheekbestanden, zodat het de context niet vervuilt wanneer de agent bijvoorbeeld implementatiescripts bewerkt. alwaysApply: false betekent dat de regel verbonden is door het matchen van bestanden, en niet in elk verzoek.

Ondersteun de regel met code

Een regel is een modelhint, geen test. Om de fout in de build op te sporen, installeert u het pakket 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 });

Als de clientmodule zelfs transitief lib/db.ts importeert, stopt next build met een begrijpelijke fout. Voor het tegenovergestelde geval is er het pakket client-only: het wordt gebruikt om de code te markeren die raakt aan window of localStorage.

Referentiepatroon voor de agent

Het is handig om een kort voorbeeld in de regel of ernaast te zetten dat de agent zal volgen:

// 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]);
}

Het achtervoegsel .client.tsx is geen Next.js-vereiste, maar een conventie. Maar zowel u als de agent kunnen aan de bestandsnaam zien waar de grens zich bevindt.

Hoe herken je een overtreding

  • Buildfout die aangeeft dat de hook alleen werkt in de Client Component betekent: de hook wordt aangeroepen in een bestand zonder "use client". De juiste reactie is om het interactieve deel eruit te halen in plaats van de hele ouder te markeren.
  • Fout dat functies niet kunnen worden doorgegeven aan clientcomponenten tenzij ze zijn gemarkeerd met "use server" - de agent heeft een handler van de servercomponent doorgegeven. Voer een serveractie uit of verplaats de handler binnen de clientcomponent.
  • Een hydratatiewaarschuwing betekent vaak dat de serveruitvoer Date.now(), Math.random() of window-afhankelijke waarden gebruikt.
  • Verdacht grote clientbundel: voer ANALYZE=true uit met @next/bundle-analyzer en controleer of deze markdown-parsers of SDK's bevat die alleen op de server mogen staan.

Wanneer deze regel overbodig is

Als het project volledig op Pages Router staat of een SPA op Vite is, is de regel nutteloos en verspilt alleen maar context. Voor een klein prototype met twee pagina's en zonder basis is één regel in de algemene regels voldoende. En onthoud: .mdc vermindert het foutenpercentage van agenten, maar vervangt server-only en diff-beoordeling niet.

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

Ещё на vbcd4u.com