Next.js 15용 Cursor .mdc: 서버와 클라이언트 구성 요소 간의 경계를 유지하는 규칙
에이전트가 앱 라우터를 중단시키는 위치
일반적인 시나리오: 커서에게 "기사 페이지에 좋아요 버튼을 추가"하도록 요청합니다. 상담원은 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 검토를 대체하지는 않습니다.