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

Cursor .mdc für Next.js 15: eine Regel, die die Grenze zwischen Server- und Client-Komponenten beibehält

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

Wo der Agent den App Router kaputt macht

Typisches Szenario: Bitten Sie Cursor, „der Artikelseite einen „Gefällt mir“-Button hinzuzufügen.“ Der Agent sieht, dass useState benötigt wird und fügt "use client" ganz oben app/blog/[slug]/page.tsx ein. Die Seite wird kompiliert, aber jetzt geht der gesamte Code, einschließlich des Artikel-Markups, in das Client-Bundle und die Abfrage an die Datenbank innerhalb der Seite funktioniert nicht mehr. Das zweite häufige Szenario: Der Agent importiert lib/db.ts wegen eines Typs in die Client-Komponente, und die Assembly stürzt ab oder, schlimmer noch, ein Modul mit Umgebungsvariablen landet im Bundle.

Das Modell kennt Ihre Grenzvereinbarungen zwischen dem Server und dem Client nicht. Sie müssen explizit in die Regel geschrieben werden, die Cursor bei der Arbeit mit App Router-Dateien ersetzt.

Gesamte Regel

Erstellen Sie eine Datei .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".

Das Feld globs beschränkt die Anwendung der Regel auf App-Router und Bibliotheksdateien, sodass der Kontext nicht verschmutzt wird, wenn der Agent beispielsweise Bereitstellungsskripts bearbeitet. alwaysApply: false bedeutet, dass die Regel durch übereinstimmende Dateien verbunden ist und nicht in jeder Anfrage.

Unterstützen Sie die Regel mit Code

Eine Regel ist ein Modellhinweis, kein Test. Um den Fehler im Build abzufangen, installieren Sie das Paket 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 });

Wenn das Client-Modul lib/db.ts auch nur transitiv importiert, stoppt next build mit einem verständlichen Fehler. Für den umgekehrten Fall gibt es das Paket client-only: Es wird verwendet, um den Code zu markieren, der window oder localStorage berührt.

Referenzmuster für den Agenten

Es ist sinnvoll, in der Regel oder daneben ein kurzes Beispiel anzugeben, dem der Agent folgen wird:

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

Das Suffix .client.tsx ist keine Next.js-Anforderung, sondern eine Konvention. Aber sowohl Sie als auch der Agent können anhand des Dateinamens erkennen, wo sich der Rand befindet.

So erkennen Sie einen Verstoß

– Build-Fehler, der besagt, dass der Hook nur in der Client-Komponente funktioniert. Das bedeutet: Der Hook wird in einer Datei ohne "use client" aufgerufen. Die richtige Antwort besteht darin, den interaktiven Teil herauszunehmen, anstatt den gesamten übergeordneten Teil zu markieren. – Fehler, dass Funktionen nicht an Clientkomponenten übergeben werden können, es sei denn, sie sind mit "use server" markiert – der Agent hat einen Handler von der Serverkomponente übergeben. Führen Sie entweder eine Serveraktion aus oder verschieben Sie den Handler innerhalb der Clientkomponente.

  • Eine Flüssigkeitswarnung bedeutet oft, dass die Serverausgabe Date.now(), Math.random() oder window-abhängige Werte verwendet.

– Verdächtig großes Client-Bundle: Führen Sie ANALYZE=true mit @next/bundle-analyzer aus und prüfen Sie, ob es Markdown-Parser oder SDKs enthält, die nur auf dem Server leben sollten.

Wenn diese Regel überflüssig ist

Wenn das Projekt vollständig auf Pages Router läuft oder ein SPA auf Vite ist, ist die Regel nutzlos und verschwendet nur Kontext. Für einen kleinen Prototypen mit zwei Seiten und ohne Basis reicht eine Zeile in den allgemeinen Regeln. Und denken Sie daran: .mdc reduziert die Fehlerrate des Agenten, ersetzt jedoch nicht server-only und die Diff-Überprüfung.

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

Ещё на vbcd4u.com