#Server-side rendering

Leaf UI loads its base and component styles automatically. This page covers only framework-specific setup. See quick start for installation and component usage.

#Next.js App Router

Put application-wide configuration in a Client Component:

'use client';

import { ConfigProvider } from '@ifhover/leaf-ui';
import type { ReactNode } from 'react';

export function Providers({ children }: { children: ReactNode }) {
  return <ConfigProvider>{children}</ConfigProvider>;
}

In your existing app/layout.tsx, wrap {children} inside <body> with Providers. Keep the layout itself as a Server Component.

Business components with event handlers, hooks or interactive state also need 'use client'. Client Components still participate in server prerendering; there is no need to set ssr: false.

#Next.js Pages Router

Place application-wide configuration in pages/_app.tsx. No 'use client' directive is needed.

For Webpack builds, add this option to your existing Next.js configuration:

export default {
  transpilePackages: ['@ifhover/leaf-ui'],
};

Append the package if you already have transpilePackages, then restart the development server. This lets Next.js process CSS inside the library and avoids the global CSS import error from node_modules. The option requires Next.js 13 or later.

The default Turbopack build in Next.js 16.4.1 needs no extra configuration. Neither build requires manual Leaf UI stylesheet imports.

#TanStack Start

Use the default Vite setup. For application-wide configuration, wrap Outlet in your existing root route, src/routes/__root.tsx:

import { ConfigProvider } from '@ifhover/leaf-ui';
import { Outlet } from '@tanstack/react-router';

function RootComponent() {
  return (
    <RootDocument>
      <ConfigProvider>
        <Outlet />
      </ConfigProvider>
    </RootDocument>
  );
}

Keep your project's existing RootDocument and the other root route options. HeadContent in <head> renders the initial stylesheet links; Scripts in <body> loads the client scripts. Start discovers component styles in the build output, so Leaf UI needs no explicit ?url stylesheet link or 'use client' directive.

See TanStack Start's root route and CSS styling guides.

#Keep the first render consistent

Use the same theme, language and initial values on the server and during client hydration. For dark mode on the first frame, read configuration from a Cookie or other server-readable data. Read preferences stored only in localStorage after mounting. See theming and switch languages for configuration.

Pass consistent initial values to dates, times and countdowns too; avoid separate new Date() calls for each side's initial render. Popups such as Modal and Message appear after mounting on the client.

#Custom SSR

When rendering directly with Node without framework-managed stylesheet discovery, import the full static stylesheet in the entry that builds your browser assets:

import '@ifhover/leaf-ui/styles/all.css';

Include the emitted CSS link in the initial HTML. The Node component entry does not import CSS and can be used directly for server rendering.