Next.js
The kit in a Next.js App Router project: keep pages and layouts on the server, and let the kit's interactive parts hydrate where they are used.
Set up
Follow the installation steps, with this components.json. Keep rsc: : it tells the CLI the project uses React Server Components, so the "use line at the top of interactive files stays in.
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "new-york",
"rsc": true,
"tsx": true,
"tailwind": { "config": "", "css": "app/globals.css", "baseColor": "zinc", "cssVariables": true },
"aliases": { "components": "@/components", "ui": "@/components/ui", "lib": "@/lib", "utils": "@/lib/utils", "hooks": "@/hooks" },
"iconLibrary": "lucide",
"registries": {
"@syncrobotic": { "url": "https://design-system.syncrobotic.me/r/{name}.json" }
}
}- Components land in
components/, robot-shell parts and blocks inui components, hooks inhooks,cninlib/and the theme inutils.ts styles/.syncrobotic-theme.css - Import them as
@/,components/ ui/ button @/. Every file starts with its item and version; see Versions and upgrades.components/ app-shell
Theme and fonts
Import the theme after Tailwind and delete the :root, .dark and @theme blocks that shadcn wrote. The theme names Geist first; serve it from your app with next/ (this site uses the geist package: npm ), never from a CDN.
@import "tailwindcss";
@import "../styles/syncrobotic-theme.css";
/* Your own dark: classes follow the class the theme switches on, not the OS setting. */
@custom-variant dark (&:where(.dark, .dark *));
/* next/font serves Geist under a generated name: put it first in the theme's font stack. */
:root {
--font-sans: var(--font-geist-sans), "Noto Sans TC", "PingFang TC", "Microsoft JhengHei", system-ui, sans-serif;
}import type { Metadata } from "next"
import { GeistSans } from "geist/font/sans"
import "./globals.css"
export const metadata: Metadata = { title: "Fleet console" }
// Runs while the HTML is parsed, before the first paint. Light is the default; "dark", or "system" on a dark system, adds
// the class. The same rule as ThemeSwitch below.
const themeScript = `try{var t=localStorage.getItem("theme");if(t==="dark"||(t==="system"&&matchMedia("(prefers-color-scheme: dark)").matches))document.documentElement.classList.add("dark")}catch(e){}`
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
// The script changes the class before React hydrates; suppressHydrationWarning lets <html> keep it.
<html lang="en" className={GeistSans.variable} suppressHydrationWarning>
<body>
<script dangerouslySetInnerHTML={{ __html: themeScript }} />
{children}
</body>
</html>
)
}next/ works the same way: Geist({ , and its .variable on <html>.
Server and client components
Pages and layouts stay Server Components: they fetch data and render. Do not add "use to a page to use a kit component. The kit's interactive components already start with "use , so you import them into a server page as they are, and only they ship JavaScript.
- Pass them data: strings, numbers, arrays and plain objects, React elements as children, and a link component (
linkAs). - Never a function from a server file: an
onValueChange, anonSelect, a Lucide icon in a nav item or tree node (icons are components). Move that part into a small file of your own that starts with"useand pass it the data.client" - A Server Function (
"use) can be passed; the Forms section below shows one.server"
Client components (78)
accordion, alarm, alert-dialog, annotated-image, attachment, autocomplete, avatar, banner, calendar, camera-feed, chart, checkbox, chip-group, choice-field, code-block, command, context-menu, copy-button, data-grid, date-selector, dialog, dock, dropdown-menu, field, file-upload, filter-form, filters, form, graph, hover-card, image-grid, input-group, input-otp, island, joint-state, label, load-more, media-player, navigation-menu, number-field, pagination, phone-input, point-cloud, popover, progress, questionnaire, radio-group, resizable, restricted-preview, robot-map, robot-model, route-progress, scroll-area, scrollspy, search-field, segmented-control, select, separator, sheet, slide-to-release, slider, sortable, spinner, stepper, stop-button, switch, table, tabs, teleop-pad, theme-toggle, time-picker, timeline, toast, toggle, toggle-group, tooltip, trace, tree
Render on the server too (25)
alert, badge, breadcrumb, button, button-group, card, description-list, empty-state, file-type, icon-tile, input, item, kbd, list, marker, meter, metric-card, page-header, share-bar, skeleton, status-eyebrow, status-glyph, text-diff, textarea, tray
The kit's hooks are for client files only. Of the 77 blocks, 72 are client components: they hold state. Either way, import them into a server page as they are.
Theme without a flash
The stored theme is only known in the browser. The inline script in the root layout above adds dark to <html> while the page is parsed, before anything paints; the switch reads the same key and keeps it in step. Mount it once, in the app shell's actions.
"use client"
import * as React from "react"
import { ThemeToggle, type ThemeChoice } from "@/components/ui/theme-toggle"
const media = "(prefers-color-scheme: dark)"
function read(): ThemeChoice {
try {
const t = localStorage.getItem("theme")
return t === "dark" || t === "system" ? t : "light"
} catch {
return "light"
}
}
function apply(choice: ThemeChoice) {
const dark = choice === "dark" || (choice === "system" && window.matchMedia(media).matches)
document.documentElement.classList.toggle("dark", dark)
}
export function ThemeSwitch() {
// The stored choice is known only in the browser: undefined on the server, so nothing shows as chosen until then.
const [choice, setChoice] = React.useState<ThemeChoice | undefined>(undefined)
React.useLayoutEffect(() => {
const stored = read()
apply(stored) // in development, Strict Mode's remount resets <html> to its JSX attributes; put the class back
setChoice(stored)
}, [])
// "Match system" follows the system live.
React.useEffect(() => {
if (choice !== "system") return
const mq = window.matchMedia(media)
const follow = () => apply("system")
mq.addEventListener("change", follow)
return () => mq.removeEventListener("change", follow)
}, [choice])
return (
<ThemeToggle
value={choice}
onValueChange={(next) => {
setChoice(next)
apply(next)
try {
localStorage.setItem("theme", next)
} catch {}
}}
/>
)
}Put the script in <body>, first, not in a hand-written <head>: on this site that made hydration fail now and then. Light is the products' default; teleoperation screens put class="dark" on their own root and stay dark.
Links: next/link through linkAs
Kit parts that render links take your router's link as linkAs and default to a plain <a>. Pass next/ (or the NavLink below, which adds route progress) and navigation stays client-side, with prefetching.
metric-card, tree, graph, chip-group, app-shell, top-bar-shell, action-rail-shell, settings-billing, notification-center
import { ChipGroup } from "@/components/ui/chip-group"
import { MetricCard, MetricGrid } from "@/components/ui/metric-card"
import { Tree, type TreeNode } from "@/components/ui/tree"
import { NavLink } from "@/components/nav-link"
// No "use client": the page reads its data on the server. ChipGroup and Tree are client components already; they get
// plain data and a link component, nothing else.
export default async function SitesPage({ searchParams }: { searchParams: Promise<{ zone?: string }> }) {
const { zone = "all" } = await searchParams
const sites: TreeNode[] = [
{
id: "north",
label: "North depot",
meta: "12 robots",
children: [
{ id: "north-a", label: "Aisle A", href: "/sites/north/a", meta: "7" },
{ id: "north-b", label: "Aisle B", href: "/sites/north/b", meta: "5" },
],
},
]
return (
<div className="flex flex-col gap-6">
<MetricGrid>
<MetricCard label="Robots online" value="12" unit="/ 14" caption="2 docked for charging" href="/robots" linkAs={NavLink} />
<MetricCard label="Open incidents" value="3" delta="+2" trend="bad" href="/incidents" linkAs={NavLink} />
</MetricGrid>
{/* Chips with href are links: the filter lives in the URL, so the page reads it from searchParams. */}
<ChipGroup
label="Zone"
value={zone}
items={[
{ value: "all", label: "All zones", href: "/sites" },
{ value: "loading", label: "Loading bays", count: 4, href: "/sites?zone=loading" },
{ value: "cold", label: "Cold store", count: 2, href: "/sites?zone=cold" },
]}
linkAs={NavLink}
/>
<Tree label="Sites" items={sites} expandAll linkAs={NavLink} />
</div>
)
}- A button that navigates:
<Button.asChild><Link href="/ missions/ new">New mission</ Link></ Button> BreadcrumbLinkrenders its own<a>: a crumb loads the page in full.Paginationbuilds its links from anhreffunction, so in a server page render it from a client file of your own.
The app shell in a layout
The layout stays on the server and renders a client frame around the page. The frame holds what cannot cross from the server: the nav with its icons, the current page from usePathname, and the link component.
import { AppFrame } from "./app-frame"
// A Server Component: it renders the client frame and passes the page through as children, which stays server-rendered.
export default function AppLayout({ children }: { children: React.ReactNode }) {
return <AppFrame>{children}</AppFrame>
}"use client"
import Image from "next/image"
import { usePathname } from "next/navigation"
import { Bot, CalendarDays, LayoutDashboard, Map } from "lucide-react"
import { AppShell, type AppNavGroup } from "@/components/app-shell"
import { NavLink } from "@/components/nav-link"
import { ThemeSwitch } from "@/components/theme-switch"
// Icons are components (functions), and functions cannot be sent from a Server Component: the nav lives here.
const nav: AppNavGroup[] = [
{
items: [
{ label: "Overview", href: "/", icon: LayoutDashboard },
{ label: "Robots", href: "/robots", icon: Bot },
{ label: "Sites", href: "/sites", icon: Map },
{ label: "Missions", href: "/missions/new", icon: CalendarDays },
],
},
]
const items = nav.flatMap((g) => g.items)
export function AppFrame({ children }: { children: React.ReactNode }) {
const pathname = usePathname()
// The nav item this page is under: /sites/north matches /sites.
const here = items.find((i) => (i.href === "/" ? pathname === "/" : pathname === i.href || pathname.startsWith(i.href + "/")))
return (
<AppShell
product="Fleet console"
logo={<Image src="/logo.svg" alt="" width={28} height={28} />}
nav={nav}
current={here?.href}
title={here?.label ?? "Fleet console"}
linkAs={NavLink}
actions={<ThemeSwitch />}
>
{children}
</AppShell>
)
}The page inside is still a Server Component: a layout passes it to the frame as children, already rendered.
Route progress
RouteProgress shows a thin blue bar while the next page loads, only after 300 ms. In the App Router, drive it from useLinkStatus, which reports a pending navigation of the <Link> it sits in. Pages that are prefetched or have a loading.tsx arrive at once and show no bar, which is right.
"use client"
import * as React from "react"
import { createPortal } from "react-dom"
import Link, { useLinkStatus } from "next/link"
import { RouteProgress } from "@/components/ui/route-progress"
// useLinkStatus reads the <Link> it sits in: pending from the click until the new page is in. The bar is portalled to
// <body>, so it is not part of the link's text or its accessible name.
function Pending() {
const { pending } = useLinkStatus()
return pending ? createPortal(<RouteProgress active />, document.body) : null
}
/** next/link with the kit's route progress. Pass it as `linkAs` to the app shell, a tree or a metric card. */
export function NavLink({ children, ...props }: React.ComponentProps<typeof Link>) {
return (
<Link {...props}>
{children}
<Pending />
</Link>
)
}Forms
Start from the form example: React Hook Form and zod drawn with the kit's Field, installed with npx . MissionForm is a client component. Save through a Server Function that returns a refusal instead of throwing it, and turn it into an error in a small client file.
"use server"
import type { MissionValues } from "@/components/form"
// A refusal is a return value: an error thrown here reaches the browser without its message in production.
export async function saveMission(values: MissionValues): Promise<{ error?: string }> {
if (values.name.toLowerCase().includes("test")) return { error: "A mission named “test” already exists on this site." }
// … write it to your API or database
return {}
}"use client"
import { useRouter } from "next/navigation"
import { MissionForm } from "@/components/form"
import { saveMission } from "./actions"
export function NewMission() {
const router = useRouter()
return (
<MissionForm
onSave={async (values) => {
const { error } = await saveMission(values)
if (error) throw new Error(error) // MissionForm shows it above the fields and keeps what was typed
router.push("/missions")
}}
/>
)
}The page (page.tsx) stays a Server Component that renders <NewMission .
The form example covers the rest: errors after the first submit, focus on the first field in error, and a button that waits.
Images
ImageGrid,AnnotatedImage,AttachmentandAvatarImagedraw a plain<img>with the URL you give, lazily loaded. They show your users' data (camera frames, uploads), often from signed storage URLs: give them a thumbnail-sized URL from your storage or image service.- Use
next/for your own pictures: the logo in the app shell (itsimage logotakes any element, as in the frame above), a marketing hero, an empty-state illustration. - Pictures from another host need that host in
images.remotePatternsinnext.config.ts.
Common errors
Hydration mismatch
The server's HTML and the browser's first render differ. The usual causes:
- A date or number formatted without a locale and time zone (
toLocaleString(),Intl.DateTimeFormat()): the server formats in its own (usually UTC, en-US), the browser in the user's. Write both down, or format on the server only. - A time that moves (
Date.now(), “3 min ago”): render it once on the server, or in a client component after mount; for a live clock,suppressHydrationWarningon its<time>. localStorageorwindowread during render: read it in an effect (as ThemeSwitch does) and passundefineduntil then.- The theme class on
<html>: expected, so<html>carriessuppressHydrationWarning.
// The locale and the time zone are written down, so the server and the browser format the same text. Show a robot's
// times in its site's zone: that is the clock the people on site read.
export function LocalTime({ iso, timeZone, locale = "en-GB" }: { iso: string; timeZone: string; locale?: string }) {
const text = new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short", timeZone }).format(new Date(iso))
return <time dateTime={iso}>{text}</time>
}Missing "use client"
A file of yours uses a hook or an event handler but has no "use line. Add it at the top of that file, or move the interactive part into a new file that has it. Kit files carry it already; if one has lost it, components.json has rsc: .
Error: You're importing a module that depends on `useState` into a React Server Component module. This API is only available in Client Components. To fix, mark the file (or its parent) with the `"use client"` directive.A function passed from the server
A server page passed a handler (or an icon, which is a component) to a kit client component. Move that part into a client file, as the app frame above does.
Error: Event handlers cannot be passed to Client Component props.
<... label="Zone" items={[...]} onValueChange={function onValueChange}>
^^^^^^^^^^^^^^^^^^^^^^^^
If you need interactivity, consider converting part of this to a Client Component.