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, Ark UI, Fidely UI v2 and theme support.

npx create-next-app -e https://github.com/fidely-ui/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

If you are using TypeScript, update your compilerOptions to include the following:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "skipLibCheck": true,
    "baseUrl": ".",
    "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>
}