Server-side rendering & Next.js

// scripts/use-client.mjs — run once: node scripts/use-client.mjs
import { readdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";

const root = "src/components/ui";
for (const entry of readdirSync(root, { withFileTypes: true })) {
  if (!entry.isDirectory()) continue;
  for (const file of readdirSync(join(root, entry.name))) {
    if (!file.endsWith(".tsx")) continue;
    const path = join(root, entry.name, file);
    const source = readFileSync(path, "utf8");
    if (!source.startsWith('"use client"')) writeFileSync(path, '"use client";\n' + source);
  }
}

# In Next.js, Tailwind v4 runs through PostCSS
npm install -D tailwindcss @tailwindcss/postcss

// postcss.config.mjs
export default {
  plugins: { "@tailwindcss/postcss": {} },
};

/* src/app/globals.css — the contents of src/index.css, only the tokens path changes */
@import "tailwindcss";
@import "../styles/tokens.css";

/* … keep the @theme, @theme inline, @utility, @keyframes and @layer base blocks of index.css as they are … */

// tsconfig.json — Next.js reads paths directly, no bundler config needed
{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

// src/app/layout.tsx — Server Component
import type { Metadata } from "next";
import { yugenHtmlAttributes, yugenThemeScript } from "@/components/ui";
import "./globals.css";
import { Providers } from "./providers";

export const metadata: Metadata = { title: "Yugen app" };

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    // The script changes attributes on <html> before hydration → silence the attribute mismatch warning for this element only.
    <html lang="en" {...yugenHtmlAttributes({ brand: "sakura" })} suppressHydrationWarning>
      <head>
        {/* Runs before the browser paints the page: data-theme from the saved choice, otherwise from the OS setting. */}
        <script dangerouslySetInnerHTML={{ __html: yugenThemeScript({ storageKey: "yugen-ui-theme" }) }} />
      </head>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

// src/app/providers.tsx
"use client";

import * as React from "react";
import { YugenProvider, type YugenTheme } from "@/components/ui";

const STORAGE_KEY = "yugen-ui-theme";

function readTheme(): YugenTheme {
  // No document on the server → "light"; on the client, read back the value the script set.
  if (typeof document === "undefined") return "light";
  const theme = document.documentElement.getAttribute("data-theme");
  return theme === "dark" || theme === "high-contrast" ? theme : "light";
}

export const SetThemeContext = React.createContext<(theme: YugenTheme) => void>(() => {});

export function Providers({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = React.useState<YugenTheme>(readTheme);

  React.useEffect(() => {
    try {
      localStorage.setItem(STORAGE_KEY, theme);
    } catch {
      /* storage blocked */
    }
  }, [theme]);

  return (
    <SetThemeContext.Provider value={setTheme}>
      <YugenProvider applyToDocument theme={theme}>
        <Toaster />
        {children}
      </YugenProvider>
    </SetThemeContext.Provider>
  );
}

// A new random nonce for every response, in the header and on the <script>:
// Content-Security-Policy: script-src 'self' 'nonce-<nonce>'
<script nonce={nonce} dangerouslySetInnerHTML={{ __html: yugenThemeScript() }} />

# yugenThemeScript() with no options, in this version
Content-Security-Policy: script-src 'self' 'sha256-aQ5/7/M1H2ZEsd4PyJ7/nRi/VlDCe/SWLVR6JGIWbgM='

// Other options: compute the hash on the server or at build time
import { createHash } from "node:crypto";
import { yugenThemeScript } from "@/components/ui";

const script = yugenThemeScript({ storageKey: "my-app-theme" }); // the same string you render in <head>
const hash = createHash("sha256").update(script).digest("base64");
// Content-Security-Policy: script-src 'self' 'sha256-${hash}'

// src/app/settings/page.tsx — Server Component: fetches data, renders Yugen components with serializable props
import { Card, CardContent, CardHeader } from "@/components/ui";
import { SettingsForm } from "./settings-form";

export default async function SettingsPage() {
  const user = await getCurrentUser();
  return (
    <Card className="max-w-lg">
      <CardHeader header="Profile" description={user.email} />
      <CardContent>
        <SettingsForm defaultName={user.name} />
      </CardContent>
    </Card>
  );
}

// src/app/settings/settings-form.tsx — everything that takes a function (onClick, render-props, toast) lives here
"use client";

import { Button, Field, Input, toast } from "@/components/ui";

export function SettingsForm({ defaultName }: { defaultName: string }) {
  return (
    <form
      className="flex flex-col gap-3"
      onSubmit={(e) => {
        e.preventDefault();
        toast({ intent: "success", title: "Profile saved" });
      }}
    >
      <Field label="Display name" required>
        <Input name="name" defaultValue={defaultName} />
      </Field>
      <Button appearance="primary" type="submit" className="self-start">
        Save
      </Button>
    </form>
  );
}