Resources

Setup: Next.js

Using BigBang with the Next.js App Router; the client component boundary, package compilation, Tailwind, brand and Provider.

Product apps are built with Vite, not Next.js (D-05): a strict hash-based CSP is proven only for client-rendered apps. This guide is for using BigBang in an internal tool or prototype built on Next.js. The general conditions are on the React app page.

Limits

@bigbang/ui components are client components: they use React state and browser events and carry no 'use client' directive. Import them only from files that start with 'use client'.
Rendering the components on the server is not tested. Keep the page frame as a server component and put the interactive parts in client components.
The packages ship as TypeScript source; Next.js has to compile them (transpilePackages).

1. Packages

pnpm add @bigbang/tokens@workspace:* @bigbang/ui@workspace:* @fontsource-variable/inter@5.3.0
pnpm add -D tailwindcss@4.3.3 @tailwindcss/postcss@4.3.3

2. Next.js config

import type { NextConfig } from 'next';

const config: NextConfig = {
  // The packages ship TypeScript source.
  transpilePackages: ['@bigbang/ui', '@bigbang/icons', '@bigbang/tokens'],
};

export default config;

export default { plugins: { '@tailwindcss/postcss': {} } };

3. Styles

@import '@bigbang/ui/styles.css';
@import '@bigbang/tokens/css/neutral-light.css';
@import '@bigbang/tokens/css/neutral-dark.css';

@source '../node_modules/@bigbang/ui/src';

4. Root layout and Provider

'use client';

import { Provider } from '@bigbang/ui';
import type { ReactNode } from 'react';

export function Providers({ children }: { children: ReactNode }) {
  return <Provider locale="en-GB">{children}</Provider>;
}

import '@fontsource-variable/inter';
import './globals.css';
import type { ReactNode } from 'react';
import { Providers } from './providers';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" data-brand="neutral" data-theme="light">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

data-theme is written on the server. To apply the user’s mode preference, read it from a cookie and write it on the html element on the server; changing it later in the browser causes a colour flash on first paint.

5. First component

'use client';

import { Button, Card } from '@bigbang/ui';

export function ExampleCard() {
  return (
    <Card className="max-w-96">
      <Card.Header>
        <Card.Title>Card title</Card.Title>
        <Card.Description>The card description goes here.</Card.Description>
      </Card.Header>
      <Card.Footer>
        <Button>Primary button</Button>
      </Card.Footer>
    </Card>
  );
}

import { ExampleCard } from './example-card';

export default function Page() {
  return (
    <main className="p-xl">
      <ExampleCard />
    </main>
  );
}