Unlock faster development with Fidely UI Pro components Coming soon

Usage with Next.js (App Router)

A guide to installing and using Fidely UI with the Next.js App Router

Get started with a template

The easiest way to get started is to use our Next.js 16 app template.
It comes preconfigured with Panda CSS, Fidely UI (v2) and theme support.

npx gitpick https://github.com/fidely-ui/fidely-templates/tree/main/next-app-template

Manual Installation

If you prefer setting things up yourself, follow the steps below.

1. install Panda CSS

npm install -D @pandacss/dev
npx panda init --postcss

2. install Fidely UI

npm install @fidely-ui/react @fidely-ui/panda-preset

3. Update package.json scripts

Open your package.json file and add the prepare script:

{
  "scripts": {
+    "prepare": "panda codegen",
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

The prepare script ensures Panda CSS generates styles automatically when dependencies are installed.

4. Update tsconfig

Note: If you're using TypeScript v5 update your compilerOptions to include the following:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": {
      "styled-system/*": ["styled-system/*"]
    }
  }
}

Note: the below is using TypeScript v6 you dont need a baseUrl

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "skipLibCheck": true,
    "paths": {
      "styled-system/*": ["./styled-system/*"]
    }
  }
}

This allows Panda’s generated styled-system files to resolve correctly.

5. Update next.config.ts file

Add transpilePackages to include @fidely-ui/react

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* config options here */
  transpilePackages: ['@fidely-ui/react'],
}

export default nextConfig

6. Configure Panda CSS

Update panda.config.ts

import { defineConfig } from '@pandacss/dev'
import { fidelyPreset } from '@fidely-ui/panda-preset'

export default defineConfig({
  presets: [fidelyPreset()],

  // Enable CSS reset
  preflight: true,

  // Files Panda should scan for styles
  include: [
    './app/**/*.{js,jsx,ts,tsx}',
    './components/**/*.{js,jsx,ts,tsx}',
    './node_modules/@fidely-ui/react/dist/panda.buildinfo.json',
  ],

  exclude: [],

  // Theme customization
  theme: {
    extend: {},
  },

  // Generate static CSS for all recipes
  staticCss: {
    recipes: '*',
  },

  // Output directory for generated styles
  outdir: 'styled-system',

  jsxFramework: 'react',

  // Remove Panda default 50 / 950 color steps
  plugins: [
    {
      name: 'panda-headless-colors',
      hooks: {
        'preset:resolved': ({ utils, preset, name }) => {
          if (name === '@pandacss/preset-panda') {
            return utils.omit(preset, [
              'theme.tokens.colors',
              'theme.semanticTokens.colors',
            ])
          }
          return preset
        },
      },
    },
  ],
})

After updating the config, generate the styled system:

npx panda codegen

7. Configure the entry CSS with layers

Navigate to app/globals.css and replace its contents with:

@layer reset, base, tokens, recipes, utilities;

You can safely delete page.module.css if it exists, it is not needed.

8. Import the global CSS in the root layout

Update your app/layout.tsx file:

import type { Metadata } from "next"
+  import "./globals.css"
...rest here

export default function RootLayout({
  children
}: Readonly<{
  children: React.ReactNode
}>) {
  return (
   <html lang="en" suppressHydrationWarning>
      <body>{children}</body>
    </html>
  )
}

The suppressHydrationWarning prop is recommended when using libraries like next-themes.

Enjoy ✨

You can now start using Fidely UI components:

import { Button } from '@fidely-ui/react'

const Demo = () => {
  return <Button>Click me</Button>
}

On this page