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

Cursor .mdc для Next.js 15: правило, яке тримає кордон Server та Client Components

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

Де агент ламає App Router

Типовий сценарій: просіть Cursor додати кнопку лайка на сторінку статті. Агент бачить, що потрібен useState, і ставить "use client" у самий верх app/blog/[slug]/page.tsx. Сторінка компілюється, але тепер весь її код, включаючи розмітку статті, йде в бандл клієнта, а запит до бази всередині сторінки перестає працювати. Другий частий варіант: агент імпортує lib/db.ts в клієнтський компонент заради одного типу, і складання падає або, гірше, в бандл потрапляє модуль зі змінними оточення.

Модель не знає ваших угод про кордон між сервером та клієнтом. Їх потрібно записати явно у правило, яке Cursor підставляє під час роботи з файлами App Router.

Правило цілком

Створіть файл .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, а угода. Зате воно дозволяє і вам, і агенту на ім'я файлу зрозуміти, де проходить кордон.

Як розпізнати порушення

  • Помилка збірки про те, що хук працює тільки в Client Component, означає: хук викликаний у файлі без "use client". Правильна реакція – винести інтерактивну частину, а не помічати весь батько.
  • Помилка про те, що функції не можна передавати до Client Components, якщо вони не позначені "use server", - агент передав обробник із серверного компонента. Або робіть Server Action або переносіть обробник всередину клієнтського компонента.
  • Попередження про гідратацію часто означає, що у серверному виведенні використані Date.now(), Math.random() або window-залежні значення.
  • Підозрительно великий клієнтський бандл: запустіть ANALYZE=true з @next/bundle-analyzer і перевірте, чи не потрапили в нього markdown-парсери або SDK, які повинні жити тільки на сервері.

Коли це правило надмірно

Якщо проект повністю на Pages Router або це SPA на Vite, правило марно і лише витрачає контекст. Для маленького прототипу, де дві сторінки немає бази, достатньо одного рядка в загальних правилах. І пам'ятайте: .mdc знижує частоту помилок агента, але не замінює server-only і рев'ю диффа.

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

Ещё на vbcd4u.com