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
Открыть все обсуждения →

에이전트가 앱 라우터를 중단시키는 위치

일반적인 시나리오: 커서에게 "기사 페이지에 좋아요 버튼을 추가"하도록 요청합니다. 상담원은 useState가 필요하다고 판단하고 "use client"를 맨 위의 app/blog/[slug]/page.tsx에 배치합니다. 페이지가 컴파일되지만 이제 기사 마크업을 포함한 모든 코드가 클라이언트 번들로 들어가고 페이지 내부의 데이터베이스에 대한 쿼리가 작동을 멈춥니다. 두 번째 일반적인 시나리오: 에이전트가 한 유형을 위해 lib/db.ts를 클라이언트 구성 요소로 가져오고 어셈블리가 충돌하거나 더 나쁜 경우 환경 변수가 있는 모듈이 번들에 포함됩니다.

모델은 서버와 클라이언트 간의 경계 계약을 알지 못합니다. 앱 라우터 파일로 작업할 때 커서가 대체하는 규칙에 명시적으로 작성되어야 합니다.

전체 규칙

.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 필드는 규칙 적용을 앱 라우터 및 라이브러리 파일로 제한하므로 에이전트가 배포 스크립트 등을 편집할 때 컨텍스트를 오염시키지 않습니다. 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인 경우 규칙은 쓸모가 없으며 컨텍스트만 낭비합니다. 두 페이지가 있고 베이스가 없는 작은 프로토타입의 경우 일반 규칙의 한 줄이면 충분합니다. 그리고 기억하세요: .mdc는 에이전트 오류율을 줄이지만 server-only 및 diff 검토를 대체하지는 않습니다.

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

Ещё на vbcd4u.com