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 composite, chart/chart-colors.ts, shell/types.ts, shell/contrast-constants.ts, shell/display-axis-constants.ts and components/ui/tabs-variants.ts. Each barrel exports them straight from those files. These are the values a server layout or a server page actually reads:

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. Every hook in the package is client-only — useShell, useIsMac, useCarousel, useContrast, useDensity, useFontSize, useChart, useFormField, useFileUpload — as are the three imperative toast calls, toast, dismissToast and toastPromise.

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

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