Server and client

Where the line is drawn

The package builds with tsup at bundle: false: every source file is transpiled to its own ESM module rather than merged into a few chunks. That is not a tree-shaking nicety, it is the reason the boundary works at all. Bundled output would push a "use client" line into the middle of a chunk, where it means nothing, and drag static primitives to the client with it.

Because the cut is per file, one export can be moved to the safe side simply by moving it to a neighbouring file with no directive. That is exactly what every *-constants.ts module in the package is for.

Two failure modes

Crossing the boundary wrongly fails in two different ways, and telling them apart is most of what you need to know. Which one you get depends on whether the thing behind the boundary is a function or a value.

The trap: seven class builders that throw

These seven are the easiest thing in the package to trip over, precisely because nothing about them suggests a boundary. They take an options object and return a string. They touch no state, no DOM, no browser API. They fail anyway, because each one is declared in the same file as its client component.

// 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'.

Two ways out

// 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>
}

The nine that are fine

Learning that one class builder is stuck tells you nothing about the next one. Nine more, plus cn, live in files that carry no directive and are callable from a server page. There is no naming convention separating the two lists — this is the list.

The quiet one: data behind a client file

A constant re-exported through a "use client" file is not blocked — it simply arrives hollow. The RSC boundary cuts by file, so a data object crossing it becomes a client-reference proxy: every property reads undefined, an array reports a length of zero, and no diagnostic fires anywhere.

// 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'

Every pure constant in the package lives in a directive-free module for this reason: *-constants.ts beside each client component, chart/chart-colors.ts, shell/types.ts, shell/contrast-constants.ts, shell/display-axis-constants.ts, components/ui/tabs-variants.ts, and since 3.0.0 the language tables in i18n/messages.ts and i18n/locale.ts. Each barrel exports them straight from those files. These are the values a server layout or a server page actually reads — and the third column is what this page read, during its own server render:

The storage keys matter most: a root layout is a Server Component, and it renders the anti-flash script for the contrast, density and text-size axes. If those three keys read undefined, the script writes to the wrong key and every display preference is silently forgotten on reload.

Hooks and toast commands

Nothing subtle here, and both groups fail loudly. All 26 hooks in the package are client-only — useShell and useIsMac as much as the stores of the components ported from Dice UI in 2.1.0 (useRating, useStepper, useTimePicker, usePhoneInput, useCropper, useKeyValueStore, useBanner, useBanners) and the two language hooks of 3.0.0 — as are the three imperative toast calls, toast, dismissToast and toastPromise. Called from a Server Component, each one throws with its own name in the message.

They are listed because a complete inventory is the point of this page, not because anybody expects them to work on a server render.

Language: the provider is client, the tables are not

Since 3.0.0 every default string in the package comes from one context, and it splits along the same per-file line as everything else here. ComitorLocaleProvider is a client component, and so are the two hooks that read it, useComitorLocale and useComitorMessages. A Server Component renders the provider — that is exactly what a root layout does, with a string locale — but cannot call the hooks.

The tables, and the functions that pick from them, are pure: comitorMessagesEn, comitorMessagesVi, COMITOR_MESSAGES, getComitorMessages(locale, override?), mergeComitorMessages, getComitorLanguage and DEFAULT_COMITOR_LOCALE. They are what a server render, a route handler or an email template reads to produce text in the user’s language with no React context to ask — the last four rows of the constants table above were read exactly that way.

// 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.

One rule is new in kind: a function cannot cross the boundary. Every key that puts a number into a sentence — members(count) in the shell table, the range and page lines of table pagination — is a function, because word order around a number changes with the language. A Server Component may call one; it may not pass one as a prop to a client component. So an override that contains a function, on the provider’s messages or on a component’s labels, is declared in a client file.

// ✗ 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>

Reading the provider moved three components across the line: Spinner, Breadcrumb and Pagination carry "use client" since 3.0.0, because their accessible names now come from it. A server page still renders all three; the one thing it cannot do with a client component — hand it a function prop — never applies, since none of the three takes one. Pagination even gained: its links call buttonVariants, so while the file was directive-free, rendering PaginationLink straight from a server page hit the very error at the top of this page. RouteTabs went the other way on purpose: it takes LinkComponent — a component, so a function — from server layouts, so the file stays directive-free and only its <nav>, which needs the provider for its name, became an internal client leaf. And all 18 components ported from Dice UI in 2.1.0 are client components; their store hooks are in the Hooks group of the table below.

What is safe on a server page

The short version, before the full table.

Every callable name

Components are omitted: a Server Component can render any of them. What follows is everything you might call or read — built from the re-export graph of all nine entries, so it is the complete list rather than a selection.

How the list stays true

A silent boundary bug cannot be caught by review, so the package gates it before publish. Three checks run on every release.

Check 3 exists because check 2 was not enough, and that was measured rather than assumed. Put CHART_COLORS in its own pure module — correct on its own, so checks 1 and 2 both stay green — but let the barrel reach it through the client chart file, and a real Next build hands a server page an object with zero keys again.