Server và client

Ranh giới nằm ở đâu

Gói build bằng tsup với bundle: false: mỗi file nguồn được transpile thành một module ESM riêng chứ không gộp vào vài chunk. Đó không phải chuyện tree-shaking cho đẹp, mà là lý do ranh giới hoạt động được. Đầu ra đã bundle sẽ đẩy một dòng "use client" vào giữa một chunk, nơi nó vô nghĩa, và kéo cả các primitive tĩnh sang client theo.

Vì ranh giới cắt theo file, một export có thể chuyển sang phía an toàn chỉ bằng cách dời nó sang một file bên cạnh không có chỉ thị. Mọi module *-constants.ts trong gói tồn tại chính là để làm việc đó.

Hai kiểu hỏng

Vượt ranh giới sai cách thì hỏng theo hai kiểu khác nhau, và phân biệt được chúng là phần lớn những gì cần biết. Gặp kiểu nào tuỳ vào thứ nằm sau ranh giới là một hàm hay một giá trị.

Cái bẫy: bảy hàm dựng class ném lỗi

Bảy hàm này là thứ dễ vấp nhất trong gói, chính vì không có gì ở chúng gợi ra một ranh giới. Chúng nhận một object tuỳ chọn và trả về một chuỗi. Chúng không chạm vào state, DOM hay API trình duyệt nào. Vậy mà vẫn hỏng, vì mỗi hàm khai trong cùng file với client component của nó.

// app/pricing/page.tsx — a Server Component. No 'use client' in this file.
import { buttonVariants } from '@comitor/ui'

export default function PricingPage() {
  return (
    <a href="/get-started" className={buttonVariants({ variant: 'outline' })}>
      Get started
    </a>
  )
}

// Build fails:
//   Attempted to call buttonVariants() from the server but buttonVariants is
//   on the client.
//
// buttonVariants only concatenates strings. It fails anyway, because it is
// declared in components/ui/button.tsx, and that file starts with 'use client'.

Hai lối ra

// The usual fix. A Server Component may RENDER a client component — that is the
// whole point of the boundary. It just may not CALL a function declared in a
// client file. Button takes asChild, so it hands its classes to your own <a>.
import { Button } from '@comitor/ui'

export default function PricingPage() {
  return (
    <Button asChild variant="outline">
      <a href="/get-started">Get started</a>
    </Button>
  )
}

// When you genuinely need the string, move the call across the boundary once.

// components/link-button.tsx
'use client'

import type { ComponentProps } from 'react'
import { buttonVariants, cn } from '@comitor/ui'

type LinkButtonProps = ComponentProps<'a'> & {
  variant?: 'default' | 'outline' | 'ghost' | 'link'
  size?: 'sm' | 'md' | 'lg'
}

export function LinkButton({ variant, size, className, ...props }: LinkButtonProps) {
  return <a className={cn(buttonVariants({ variant, size }), className)} {...props} />
}

// app/pricing/page.tsx — still a Server Component
import { LinkButton } from '@/components/link-button'

export default function PricingPage() {
  return <LinkButton href="/get-started" variant="outline">Get started</LinkButton>
}

Chín hàm không sao

Biết một hàm dựng class bị kẹt không cho biết gì về hàm kế tiếp. Chín hàm nữa, cộng cn, nằm trong file không có chỉ thị và gọi được từ trang server. Không có quy ước đặt tên nào tách hai danh sách — danh sách chính là đây.

Kiểu lặng lẽ: dữ liệu nằm sau một file client

Một hằng được re-export qua một file "use client" không bị chặn — nó tới nơi nhưng rỗng ruột. Ranh giới RSC cắt theo file, nên một object dữ liệu đi qua nó trở thành proxy tham chiếu client: mọi thuộc tính đọc ra undefined, mảng báo độ dài bằng không, và không có chẩn đoán nào bật lên ở đâu cả.

// The shape of the quiet bug. Same boundary, no error.
// The constant sits in the right module — and still arrives hollow, because the
// only path from the entry to it crosses a client file.

// chart/comitor-chart.tsx
'use client'
export { CHART_COLORS } from './chart-colors.js'   // ← re-exported THROUGH a client file

// app/report/page.tsx — a Server Component
import { CHART_COLORS } from '@comitor/ui/chart'

CHART_COLORS.gold           // undefined  — not 'var(--chart-1)'
Object.keys(CHART_COLORS)   // []         — the object arrives with no keys

// Nothing throws. Nothing warns. TypeScript still reports the literal type, so
// the editor stays green too. The chart renders with every series undefined.

// What the package does instead. The constant lives in a directive-free module,
// and the barrel exports it STRAIGHT from there — routing it through the client
// file would put it back behind the boundary.

// shell/contrast-constants.ts   — no directive, on purpose
export const CONTRAST_STORAGE_KEY = 'comitor-contrast'

// shell/index.ts
export * from './contrast-constants.js'    // not via contrast-provider.tsx
export * from './contrast-provider.js'

// app/layout.tsx — a Server Component
import { CONTRAST_STORAGE_KEY } from '@comitor/ui/shell'

CONTRAST_STORAGE_KEY   // 'comitor-contrast'

Mọi hằng thuần trong gói nằm trong module không có chỉ thị vì lý do này: *-constants.ts cạnh mỗi client component, chart/chart-colors.ts, shell/types.ts, shell/contrast-constants.ts, shell/display-axis-constants.ts, components/ui/tabs-variants.ts, và từ 3.0.0 là các bảng ngôn ngữ trong i18n/messages.ts và i18n/locale.ts. Mỗi barrel export chúng thẳng từ các file đó. Đây là các giá trị mà một layout hay một trang server thật sự đọc — và cột thứ ba là thứ trang này đọc được, trong lần server render của chính nó:

Các khoá lưu trữ quan trọng nhất: root layout là một Server Component, và nó render script chống nháy cho các trục tương phản, mật độ và cỡ chữ. Nếu ba khoá đó đọc ra undefined, script ghi vào sai khoá và mọi tuỳ chọn hiển thị lặng lẽ bị quên sau khi tải lại.

Hook và lệnh toast

Không có gì tinh vi ở đây, và cả hai nhóm đều hỏng ồn ào. Cả 26 hook trong gói đều chỉ chạy ở client — từ useShell, useIsMac tới store của các component chuyển từ Dice UI ở 2.1.0 (useRating, useStepper, useTimePicker, usePhoneInput, useCropper, useKeyValueStore, useBanner, useBanners) và hai hook ngôn ngữ của 3.0.0 — và ba lệnh toast kiểu mệnh lệnh, toast, dismissToast và toastPromise, cũng vậy. Gọi từ một Server Component, mỗi thứ ném lỗi có tên của chính nó trong thông báo.

Chúng có mặt vì mục đích của trang này là một bản kiểm kê đầy đủ, chứ không phải vì ai đó trông chờ chúng chạy được khi server render.

Ngôn ngữ: provider là client, các bảng thì không

Từ 3.0.0, mọi chuỗi mặc định của gói đến từ một context, và nó cũng tách theo đúng đường ranh theo file như mọi thứ khác ở đây. ComitorLocaleProvider là một client component, hai hook đọc nó cũng vậy: useComitorLocale và useComitorMessages. Server Component render được provider — root layout làm đúng việc đó, với locale là một chuỗi — nhưng không gọi được các hook.

Các bảng, và các hàm chọn từ chúng, là thuần: comitorMessagesEn, comitorMessagesVi, COMITOR_MESSAGES, getComitorMessages(locale, override?), mergeComitorMessages, getComitorLanguage và DEFAULT_COMITOR_LOCALE. Đây là thứ một lần server render, một route handler hay một mẫu email đọc để sinh chữ theo ngôn ngữ của người dùng khi không có context React nào để hỏi — bốn hàng cuối của bảng hằng phía trên được đọc đúng theo cách đó.

// app/invoices/empty.tsx — a Server Component. No hook and no provider: the string
// tables are plain data, so the server picks the user's language itself.
import { getComitorMessages } from '@comitor/ui'
import { getLocale } from 'next-intl/server'

export default async function NoInvoices() {
  const { dataTable } = getComitorMessages(await getLocale())
  return <p>{dataTable.emptyTitle}</p> // 'No data yet' · 'Chưa có dữ liệu'
}

// The same call works in a route handler, a Server Action or an email template —
// anywhere text must be in the user's language and there is no React tree to
// hold a ComitorLocaleProvider.

Có một luật mới về bản chất: hàm không đi qua được ranh giới. Mọi khoá đặt một con số vào câu — members(count) trong bảng shell, dòng khoảng và dòng trang của phân trang bảng — đều là hàm, vì trật tự từ quanh con số đổi theo ngôn ngữ. Server Component được gọi một hàm như vậy; nó không được truyền hàm đó làm prop cho client component. Nên một override có chứa hàm, ở messages của provider hay ở labels của một component, phải khai trong một file client.

// ✗ app/layout.tsx — a Server Component. `members` is a function, and React refuses
//   it at the boundary: "Functions cannot be passed directly to Client Components".
<ComitorLocaleProvider locale={locale} messages={{ shell: { members: (n) => `${n} seats` } }}>

// ✓ app/providers.tsx — the same override, declared on the client side.
'use client'

import { ComitorLocaleProvider, getComitorLanguage } from '@comitor/ui'
import type { ComitorLanguage, ComitorMessagesOverride } from '@comitor/ui'

// Module scope keeps the reference stable; one per language, because an override
// is written in one.
const SEATS: Record<ComitorLanguage, ComitorMessagesOverride> = {
  en: { shell: { members: (count) => `${count} ${count === 1 ? 'seat' : 'seats'}` } },
  vi: { shell: { members: (count) => `${count} chỗ` } },
}

export function Providers({ locale, children }: { locale: string; children: React.ReactNode }) {
  return (
    <ComitorLocaleProvider locale={locale} messages={SEATS[getComitorLanguage(locale)]}>
      {children}
    </ComitorLocaleProvider>
  )
}

// …and the root layout passes only a string: <Providers locale={locale}>{children}</Providers>

Việc đọc provider đã đẩy ba component sang phía bên kia: Spinner, Breadcrumb và Pagination mang "use client" từ 3.0.0, vì tên truy cập của chúng giờ lấy từ provider. Trang server vẫn render được cả ba; điều duy nhất nó không làm được với client component — truyền cho nó một prop là hàm — không bao giờ xảy ra, vì không cái nào trong ba nhận prop như vậy. Pagination còn được lợi: link của nó gọi buttonVariants, nên hồi file còn chưa có chỉ thị, render PaginationLink thẳng từ trang server dính đúng lỗi ở đầu trang này. RouteTabs cố ý đi hướng ngược lại: nó nhận LinkComponent — một component, tức là một hàm — từ layout server, nên file giữ không chỉ thị và chỉ có <nav> của nó, thứ cần provider để lấy tên, thành một lá client nội bộ. Và cả 18 component chuyển từ Dice UI ở 2.1.0 đều là client component; hook store của chúng nằm trong nhóm Hook của bảng dưới.

Thứ gì an toàn trên trang server

Bản ngắn, trước bảng đầy đủ.

Mọi tên có thể gọi

Component được bỏ qua: Server Component render được bất kỳ cái nào. Phần dưới là mọi thứ có thể gọi hoặc đọc — dựng từ đồ thị re-export của cả chín entry, nên đây là danh sách đầy đủ chứ không phải một phần chọn lọc.

Danh sách giữ đúng bằng cách nào

Lỗi ranh giới lặng lẽ thì review không bắt được, nên gói chặn nó trước khi phát hành. Ba bước kiểm chạy ở mỗi bản phát hành.

Bước 3 tồn tại vì bước 2 không đủ, và điều đó đã được đo chứ không phải đoán. Đặt CHART_COLORS vào module thuần riêng — tự nó là đúng, nên bước 1 và 2 vẫn xanh — nhưng để barrel đi tới nó qua file chart client, thì một lần build Next thật lại đưa cho trang server một object không có khoá nào.