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

Next.js 15 の Cursor .mdc: サーバー コンポーネントとクライアント コンポーネント間の境界を維持するルール

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

エージェントが App Router を破壊する場所

典型的なシナリオ: Cursor に「記事ページにいいね! ボタンを追加する」よう依頼します。エージェントは useState が必要であることを認識し、"use client" を app/blog/[slug]/page.tsx の一番上に置きます。ページはコンパイルされますが、記事のマークアップを含むすべてのコードがクライアント バンドルに入り、ページ内のデータベースへのクエリが機能しなくなります。 2 番目の一般的なシナリオ: エージェントが 1 つのタイプのためにクライアント コンポーネントに lib/db.ts をインポートすると、アセンブリがクラッシュするか、さらに悪いことに、環境変数を含むモジュールがバンドル内に組み込まれてしまいます。

モデルは、サーバーとクライアント間の境界合意を認識しません。これらは、App Router ファイルを操作するときに Cursor が置き換えるルールに明示的に書き込む必要があります。

ルール全体

ファイル .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".

globs フィールドは、ルールの適用を App Router とライブラリ ファイルに制限するため、エージェントが展開スクリプトなどを編集するときにコンテキストを汚染しません。 alwaysApply: false は、ルールがすべてのリクエストではなく、一致するファイルによって接続されていることを意味します。

コードでルールをサポートする

ルールはモデルのヒントであり、テストではありません。ビルドでエラーを検出するには、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 });

クライアント モジュールが推移的に lib/db.ts をインポートした場合でも、next build は理解できるエラーで停止します。逆の場合には、client-only パッケージがあります。これは、window または localStorage に触れるコードをマークするために使用されます。

エージェントの参照パターン

エージェントが従う短い例をルール内またはルールの隣に置くと便利です。

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

.client.tsx サフィックスは Next.js の要件ではなく、規則です。ただし、ファイル名によって境界線がどこにあるのかをあなたとエージェントの両方が理解できるようになります。

違反を認識する方法

  • フックがクライアント コンポーネントでのみ機能することを示すビルド エラーは、フックが "use client" のないファイルで呼び出されていることを意味します。正しい対応は、親全体にフラグを立てるのではなく、インタラクティブな部分を削除することです。
  • "use server" でマークされていない限り、関数をクライアント コンポーネントに渡すことができないというエラー - エージェントがサーバー コンポーネントからハンドラーを渡しました。サーバー アクションを実行するか、ハンドラーをクライアント コンポーネント内に移動します。
  • ハイドレーション警告は、多くの場合、サーバー出力で Date.now()、Math.random()、または window に依存する値が使用されていることを意味します。
  • 疑わしい大規模なクライアント バンドル: @next/bundle-analyzer を指定して ANALYZE=true を実行し、サーバー上にのみ存在すべきマークダウン パーサーまたは SDK が含まれているかどうかを確認します。

このルールが冗長な場合

プロジェクトが完全に Pages Router 上にある場合、または Vite 上の SPA である場合、ルールは役に立たず、コンテキストを無駄にするだけです。 2 ページでベースのない小さなプロトタイプの場合、一般ルールは 1 行で十分です。 .mdc はエージェントのエラー率を減らしますが、server-only と差分レビューを置き換えるものではないことを覚えておいてください。

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

Ещё на vbcd4u.com