Installation

Using Panda CSS with Next.js

Panda CSS works out of the box with Next.js. You can use Panda CSS with Next.js by following the steps below.

If you don't have Next.js app installed, you can follow the Create a Next.js app section to create a new Next.js app, otherwise you can skip to the Install Panda CSS section.

Start a new project

You can chose between these two options to start a new project:

Using App RouterUsing Pages Router

Create a Next.js app

First, create a Next.js app using the official Create Next App (opens in a new tab) CLI. We will name our project test-app but you can name it whatever you want.

If you don't enter any parameter, the CLI will guide you through the process of creating a new Next.js app.

pnpm dlx create-next-app@latest --use-pnpm

You will be asked a few questions, answer them as follows:

✔ What is your project named? … test-app
✔ Would you like to use TypeScript with this project? … Yes
✔ Would you like to use ESLint with this project? … Yes
✔ Would you like to use Tailwind CSS with this project? … No
✔ Would you like to use `src/` directory with this project? … Yes
✔ Use App Router (recommended)? … Yes
✔ Would you like to customize the default import alias? … No

Enter the newly created directory:

cd test-app

Install Panda CSS

Install Panda CSS dependency using your favorite package manager.

pnpm install -D @pandacss/dev
pnpm panda init --postcss

panda init --postcss command will automatically create a postcss.config.js file at the root of your project with the following code:

module.exports = {
  plugins: {
    '@pandacss/dev/postcss': {},
  },
}

For advanced configuration follow the Next.js PostCSS guide to set up a custom PostCSS configuration by referring to this link (opens in a new tab).

Update package.json scripts

Open your package.json file and update the scripts section as follows:

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

The prepare script that will run codegen after dependency installation. Read more about codegen in the CLI section.

💡

This step ensures that the panda output directory is regenerated after each dependency installation. So you can add the output directory to your .gitignore file and not worry about it.

Configure the content

Make sure that all of the paths of your React components are included in the include section of the panda.config.ts file.

panda.config.ts
import { defineConfig } from "@pandacss/dev"
 
export default defineConfig({
// Whether to use css reset
preflight: true,
 
// Where to look for your css declarations
include: ["./src/components/**/*.{ts,tsx,js,jsx}", "./src/app/**/*.{ts,tsx,js,jsx}"],
 
// Files to exclude
exclude: [],
 
// The output directory for your css system
outdir: "styled-system",
})

Configure the entry CSS with layers

In your Next.js project, navigate to the src/app folder and open global.css file. Replace all the content with the following code:

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

Note: Feel free to remove the page.module.css file as we don't need it anymore.

Import the entry CSS in your app

Make sure that you import the global.css file in your src/app/layout.tsx file as follows:

./src/app/layout.tsx
  import './global.css'
  import { Inter } from 'next/font/google'
 
  const inter = Inter({ subsets: ['latin'] })
 
  export const metadata = {
    title: 'Create Next App',
    description: 'Generated by create next app',
  }
 
  export default function RootLayout({
    children,
  }: {
    children: React.ReactNode
  }) {
    return (
      <html lang="en">
        <body className={inter.className}>{children}</body>
      </html>
    )
  }

Start using Panda

We will update the contents of src/app/page.tsx with the following snippet that uses Panda CSS:

  import { css } from '../../styled-system/css';
 
  export default function Home() {
    return (
      <div className={css({ fontSize: "2xl", fontWeight: 'bold' })}>Hello 🐼!</div>
    )
  }

Start the development server

Run the following command to start the development server:

pnpm dev

Open http://localhost:3000 (opens in a new tab) with your browser to see the result.

Troubleshooting

I don't see any styles

Sometimes Next.js caches PostCSS generated styles and when that happens you need to clear the cache. To do that, delete the .next folder and restart your development server.

You can also update you package.json scripts to delete the .next folder before each build:

{
  "scripts": {
-    "dev": "next dev",
+    "dev": "rm -rf .next && next dev",
  },
}

This is a known issue with Next.js and you can track the progress here:

I don't see any import autocomplete in my IDE

If you're not getting import autocomplete in your IDE, you may need to include the styled-system directory in your tsconfig.json file:

tsconfig.json
{
  // ...
  "include":  ["src", "styled-system"]
}

Codegen fails using es5

If you run into any error related to "Transforming const to the configured target environment ("es5") is not supported yet", update your tsconfig to use es6 or higher:

tsconfig.json
{
  "compilerOptions": {
    "target": "es6",
  }
}
AstroRemix