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

Kursor .mdc untuk Next.js 15: aturan yang menjaga batas antara Komponen Server dan Klien

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

Dimana agen merusak App Router

Skenario umum: minta Kursor untuk “menambahkan tombol suka ke halaman artikel.” Agen melihat bahwa useState diperlukan dan menempatkan "use client" di bagian paling atas app/blog/[slug]/page.tsx. Halaman dikompilasi, tetapi sekarang semua kodenya, termasuk markup artikel, masuk ke bundel klien, dan kueri ke database di dalam halaman berhenti berfungsi. Skenario umum kedua: agen mengimpor lib/db.ts ke komponen klien demi satu jenis, dan rakitan mogok atau, lebih buruk lagi, modul dengan variabel lingkungan berakhir di bundel.

Model tidak mengetahui perjanjian batas Anda antara server dan klien. Mereka perlu ditulis secara eksplisit ke dalam aturan yang menggantikan Cursor saat bekerja dengan file App Router.

Seluruh aturan

Buat file .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".

Bidang globs membatasi penerapan aturan pada Router Aplikasi dan file pustaka, sehingga tidak mencemari konteks saat agen mengedit, misalnya, skrip penerapan. alwaysApply: false berarti aturan dihubungkan dengan mencocokkan file, dan tidak di setiap permintaan.

Dukung aturan dengan kode

Aturan adalah petunjuk model, bukan ujian. Untuk mengetahui kesalahan dalam build, instal 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 });

Jika modul klien mengimpor lib/db.ts secara transitif, next build akan berhenti dengan kesalahan yang dapat dimengerti. Untuk kasus sebaliknya, ada paket client-only: digunakan untuk menandai kode yang menyentuh window atau localStorage.

Pola referensi untuk agen

Akan berguna untuk memberikan contoh singkat pada atau di samping aturan yang akan diikuti oleh agen:

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

Akhiran .client.tsx bukanlah persyaratan Next.js, tetapi sebuah konvensi. Tapi ini memungkinkan Anda dan agen untuk memahami dengan nama file di mana perbatasannya berada.

Cara mengenali pelanggaran

  • Kesalahan build yang menyatakan bahwa hook hanya berfungsi di Komponen Klien berarti: hook dipanggil dalam file tanpa "use client". Respons yang benar adalah dengan menghilangkan bagian interaktif daripada menandai seluruh induk.
  • Kesalahan karena fungsi tidak dapat diteruskan ke Komponen Klien kecuali jika ditandai dengan "use server" - agen meneruskan pengendali dari komponen server. Lakukan Tindakan Server, atau pindahkan pengendali ke dalam komponen klien.
  • Peringatan hidrasi sering kali berarti keluaran server menggunakan nilai yang bergantung pada Date.now(), Math.random(), atau window.
  • Paket klien berukuran besar yang mencurigakan: jalankan ANALYZE=true dengan @next/bundle-analyzer dan periksa apakah paket tersebut berisi parser atau SDK penurunan harga yang seharusnya hanya ada di server.

Ketika aturan ini mubazir

Jika proyek sepenuhnya berada di Pages Router atau merupakan SPA di Vite, aturan tersebut tidak berguna dan hanya membuang-buang konteks. Untuk prototipe kecil dengan dua halaman dan tanpa dasar, satu baris pada aturan umum sudah cukup. Dan ingat: .mdc mengurangi tingkat kesalahan agen, tetapi tidak menggantikan server-only dan tinjauan berbeda.

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

Ещё на vbcd4u.com