Next.js 15 के लिए कर्सर .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 हैं जो केवल सर्वर पर रहना चाहिए।
जब यह नियम बेमानी हो
यदि प्रोजेक्ट पूरी तरह से पेज राउटर पर है या वाइट पर एक एसपीए है, तो नियम बेकार है और केवल संदर्भ को बर्बाद करता है। दो पृष्ठों और बिना आधार वाले एक छोटे प्रोटोटाइप के लिए, सामान्य नियमों में एक पंक्ति पर्याप्त है। और याद रखें: .mdc एजेंट त्रुटि दर को कम करता है, लेकिन server-only और भिन्न समीक्षा को प्रतिस्थापित नहीं करता है।