Getting StartedDesign TokensComponents

Next.js Setup

Complete guide to setting up Vibrant UI in your Next.js application

Ready to make your Next.js app absolutely stunning? This guide will walk you through setting up Vibrant UI in your Next.js project.

Prerequisites

Before we start, make sure you have:

  • Node.js 18+ installed
  • A Next.js 13+ project with the App Router
  • Access to GitHub packages (see Authorization)

Installation

Install the core Vibrant UI packages:

npm install @vibrant-ui/components @vibrant-ui/core @vibrant-ui/styles
pnpm add @vibrant-ui/components @vibrant-ui/core @vibrant-ui/styles
yarn add @vibrant-ui/components @vibrant-ui/core @vibrant-ui/styles
bun add @vibrant-ui/components @vibrant-ui/core @vibrant-ui/styles

For icons, you'll also need Font Awesome Pro:

npm install @fortawesome/pro-regular-svg-icons
pnpm add @fortawesome/pro-regular-svg-icons
yarn add @fortawesome/pro-regular-svg-icons
bun add @fortawesome/pro-regular-svg-icons

Configuration

1. Next.js Config

Create or update your next.config.ts file to include Vanilla Extract support and package optimization:

import { createVanillaExtractPlugin } from '@vanilla-extract/next-plugin';
import type { NextConfig } from 'next';

const withVanillaExtract = createVanillaExtractPlugin({
  identifiers: process.env.NODE_ENV === 'development' ? 'debug' : 'short',
});

const nextConfig: NextConfig = {
  experimental: {
    optimizePackageImports: ['@vibrant-ui/components', '@vibrant-ui/core', '@vibrant-ui/styles'],
  },
  transpilePackages: ['@vibrant-ui/components', '@vibrant-ui/core', '@vibrant-ui/styles'],
};

export default withVanillaExtract(nextConfig);

2. Install Dependencies

Add the required Vanilla Extract dependencies:

npm install @vanilla-extract/next-plugin @vanilla-extract/css
pnpm add @vanilla-extract/next-plugin @vanilla-extract/css
yarn add @vanilla-extract/next-plugin @vanilla-extract/css
bun add @vanilla-extract/next-plugin @vanilla-extract/css

3. Root Layout Setup

Update your app/layout.tsx to include Vibrant UI's theme provider and styles:

import { createTheme } from '@vibrant-ui/core';
import { baseStyle, resetsStyle } from '@vibrant-ui/styles';
import clsx from 'clsx';
import type { Metadata } from 'next';
import type { ReactNode } from 'react';
import { ThemeProvider } from './theme-provider';

export const metadata: Metadata = {
  title: 'My Vibrant App',
  description: 'Built with Vibrant UI',
};

export default function RootLayout({
  children
}: {
  children: ReactNode
}) {
  const theme = createTheme({
    colors: { primary: 'blue' }, // Choose your primary color
    neutral: 'slate', // Choose your neutral color
    scheme: 'auto', // or 'light' | 'dark'
  });

  return (
    <html
      {...theme.htmlProps}
      className={clsx(resetsStyle, baseStyle)}
      lang="en"
    >
      <body>
        <ThemeProvider theme={theme.config}>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

4. Theme Provider Component

Create a client-side theme provider at app/theme-provider.tsx:

'use client';

import {
  type ThemeConfiguration,
  ThemeProvider as VibrantUIProvider
} from '@vibrant-ui/core';
import type { ReactNode } from 'react';

export interface ThemeProviderProps {
  children?: ReactNode;
  theme: ThemeConfiguration;
}

export function ThemeProvider({ children, theme }: ThemeProviderProps) {
  return (
    <VibrantUIProvider theme={theme}>
      {children}
    </VibrantUIProvider>
  );
}

Your First Component

Now let's create your first page with Vibrant UI components! Update your app/page.tsx:

import {
  Button,
  Card,
  Text,
  VStack,
  HStack,
  Container
} from '@vibrant-ui/components';

export default function HomePage() {
  return (
    <Container maxWidth="2xl" padding="xl">
      <VStack gap="xl" align="center">
        <Text size="4xl" weight="bold" color="primary">
          Welcome to Vibrant UI! 🎉
        </Text>

        <Text size="lg" color="neutral" strength="weaker">
          Your Next.js app is now powered by beautiful components
        </Text>

        <Card padding="lg" width="full" variant="subtle">
          <VStack gap="md">
            <Text weight="bold">Button Examples</Text>
            <HStack gap="sm">
              <Button variant="solid" color="primary">
                Primary
              </Button>
              <Button variant="outlined" color="green">
                Success
              </Button>
              <Button variant="soft" color="red">
                Danger
              </Button>
            </HStack>
          </VStack>
        </Card>

        <HStack gap="sm">
          <Button variant="transparent" size="sm">
            Small
          </Button>
          <Button variant="soft" size="md">
            Medium
          </Button>
          <Button variant="solid" size="lg">
            Large
          </Button>
        </HStack>
      </VStack>
    </Container>
  );
}

Advanced Features

Color Scheme Toggle

Add a dark/light mode toggle to your app:

'use client';

import { Button } from '@vibrant-ui/components';
import { useTheme } from '@vibrant-ui/core';

export function ColorSchemeToggle() {
  const { scheme, setScheme } = useTheme();

  return (
    <Button
      variant="soft"
      onPress={() => setScheme(scheme === 'dark' ? 'light' : 'dark')}
    >
      {scheme === 'dark' ? '☀️' : '🌙'}
    </Button>
  );
}

App Layout

For more complex layouts, use the AppLayout components:

import {
  AppLayout,
  AppLayoutPanel,
  AppLayoutTopBar,
  Text,
  Spacer
} from '@vibrant-ui/components';
import { ColorSchemeToggle } from './color-scheme-toggle';

export default function DashboardLayout({
  children
}: {
  children: ReactNode
}) {
  return (
    <AppLayout>
      <AppLayoutTopBar>
        <Text weight="bold">My App</Text>
        <Spacer />
        <ColorSchemeToggle />
      </AppLayoutTopBar>
      <AppLayoutPanel>
        {children}
      </AppLayoutPanel>
    </AppLayout>
  );
}

TypeScript Configuration

Make sure your tsconfig.json includes proper module resolution:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "incremental": true,
    "esModuleInterop": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

What's Next?

Congratulations! You now have Vibrant UI running in your Next.js app! Here's what you can explore next:

Troubleshooting

Build Errors

If you encounter build errors, make sure:

  • All peer dependencies are installed
  • Your Next.js version is 13+
  • Vanilla Extract plugin is properly configured

Styling Issues

If components don't look right:

  • Ensure resetsStyle and baseStyle are applied to your html element
  • Check that your theme is properly configured
  • Verify the ThemeProvider wraps your app

Need help? Check out our playground source code for a complete working example!

Edit on GitHub

Last updated on

Getting Started

Get started with Vibrant UI