Next.js 15 için imleç .mdc: Sunucu ve İstemci Bileşenleri arasındaki sınırı koruyan bir kural
Aracının Uygulama Yönlendiricisini kırdığı yer
Tipik senaryo: İmleçten "makale sayfasına beğen düğmesi eklemesini" isteyin. Aracı, useState'un gerekli olduğunu görür ve "use client"'u en üste app/blog/[slug]/page.tsx koyar. Sayfa derlenir, ancak artık makale işaretlemesi de dahil olmak üzere tüm kodlar istemci paketine gider ve sayfanın içindeki veritabanına yapılan sorgu çalışmayı durdurur. İkinci yaygın senaryo: Aracı, tek bir tür uğruna istemci bileşenine lib/db.ts aktarır ve derleme çöker veya daha kötüsü, ortam değişkenlerine sahip bir modül pakette kalır.
Model, sunucu ile istemci arasındaki sınır anlaşmalarınızı bilmiyor. Bunların, Uygulama Yönlendirici dosyalarıyla çalışırken İmlecin değiştirdiği kurala açıkça yazılması gerekir.
Kuralın tamamı
Bir dosya oluşturun .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 alanı, kuralın uygulamasını Uygulama Yönlendiricisi ve kitaplık dosyalarıyla sınırlar, böylece aracı örneğin dağıtım komut dosyalarını düzenlediğinde bağlamı kirletmez. alwaysApply: false, kuralın her istekte değil, eşleşen dosyalarla bağlandığı anlamına gelir.
Kuralı kodla destekleyin
Kural bir test değil, model ipucudur. Derlemedeki hatayı yakalamak için server-only paketini yükleyin:
npm install server-only
// lib/db.ts
import "server-only";
import { Pool } from "pg";
export const pool = new Pool({ connectionString: process.env.DATABASE_URL });İstemci modülü geçişli olarak lib/db.ts'u içe aktarsa bile, next build anlaşılır bir hatayla duracaktır. Bunun tersi durumda, client-only paketi vardır: window veya localStorage'a dokunan kodu işaretlemek için kullanılır.
Aracı için referans modeli
Kuralın içine veya yanına aracının izleyeceği kısa bir örnek koymak yararlı olacaktır:
// 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 son eki bir Next.js gereksinimi değil, bir kuraldır. Ancak dosya adına göre hem sizin hem de temsilcinin sınırın nerede olduğunu anlamasını sağlar.
İhlal nasıl anlaşılır?
- Kancanın yalnızca İstemci Bileşeninde çalıştığını belirten derleme hatası şu anlama gelir: kanca
"use client"olmadan bir dosyada çağrılır. Doğru yanıt, ebeveynin tamamını işaretlemek yerine etkileşimli kısmı çıkarmaktır. - İşlevlerin,
"use server"ile işaretlenmedikçe İstemci Bileşenlerine aktarılamaması hatası - aracı, sunucu bileşeninden bir işleyici aktardı. Bir Sunucu Eylemi gerçekleştirin veya işleyiciyi istemci bileşeninin içine taşıyın. - Bir hidrasyon uyarısı genellikle sunucu çıkışının
Date.now(),Math.random()veyawindow'a bağlı değerleri kullandığı anlamına gelir. - Şüphe uyandıracak kadar büyük istemci paketi:
ANALYZE=true'yi@next/bundle-analyzerile çalıştırın ve yalnızca sunucuda yaşaması gereken herhangi bir işaretleme ayrıştırıcısı veya SDK içerip içermediğini kontrol edin.
Bu kural gereksiz olduğunda
Proje tamamen Pages Router'daysa veya Vite'ta bir SPA ise, kural işe yaramaz ve yalnızca bağlamı boşa harcar. İki sayfalı ve tabanı olmayan küçük bir prototip için genel kurallardaki bir satır yeterlidir. Ve unutmayın: .mdc aracı hata oranını azaltır ancak server-only ve fark incelemesinin yerini almaz.