Usage with Next.js (Page Router)

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

Get started with a template

The easiest way to get started is to use our Next.js 16 page 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-page-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'],
}

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: [
    './pages/**/*.{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 styles/globals.css and replace its contents with:

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

You can safely remove any unused CSS modules if present.

8. Import global CSS in _app.tsx

Update pages/_app.tsx file:

import type { AppProps } from "next/app"
+  import "../styles/globals.css"

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

Enjoy ✨

You can now start using Fidely UI components:

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

export default function Home() {
  return <Button>Click me</Button>
}