Installation

Using Panda CSS with React Router

Setting up Panda CSS in a React Router project using PostCSS.

Start a new project

Create React Router project

To get started, we will need to create a new React Router project using the official Create React Router (opens in a new tab) CLI. In this guide, we will use TypeScript.

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

pnpm dlx create-react-router@latest

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

? Where should we create your new project? test-app
? Install dependencies? No
💡

Note: You should decline the dependency installation step as we will install dependencies together with Panda CSS.

Install Panda

Install panda and create your panda.config.ts file.

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

Update package.json scripts

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

package.json
{
  "scripts": {
+    "prepare": "panda codegen",
    "build": "cross-env NODE_ENV=production react-router build",
    "dev": "react-router dev",
    "start": "cross-env NODE_ENV=production react-router-serve ./build/server/index.js",
    "typecheck": "react-router typegen && tsc"
  },
}
  • "prepare" - script that will run Panda CSS CLI codegen before each build. 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 Panda CSS output directory to your .gitignore file and not worry about it.

Configure the content

Make sure that all of the paths of your React Router 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: ["./app/**/*.{ts,tsx,js,jsx}"],
 
 // Files to exclude
 exclude: [],
 
 // The output directory for your css system
 outdir: "styled-system",
})

Next replace the built-in TailwindCSS plugin with PandaCSS.

vite.config.ts
import { reactRouter } from "@react-router/dev/vite";
import autoprefixer from "autoprefixer";
import pandacss from "@pandacss/dev/postcss";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";
 
export default defineConfig({
  css: {
    postcss: {
      plugins: [pandacss, autoprefixer],
    },
  },
  plugins: [reactRouter(), tsconfigPaths()],
});
 

Configure the entry CSS with layers

Create a new file app/index.css and add the following content:

app/index.css
@layer reset, base, tokens, recipes, utilities;

Import the index.css file in your app/root.tsx file and add the styles variable to the links function.

Please note the ?url query parameter in the import statement. This is required by Vite to generate the correct path to the CSS file.

app/root.tsx
import {
  isRouteErrorResponse,
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
} from "react-router";
 
import type { Route } from "./+types/root";
import styles from "./index.css?url";
 
export const links: LinksFunction = () => [
  // ...
  { rel: "stylesheet", href: styles },
];
 
export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Start your build process

Run the following command to start your development server.

pnpm dev

Start using Panda

Now you can start using Panda CSS in your project. Here is the snippet of code that you can use in your app/routes/_index.tsx file.

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

Troubleshooting

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":  ["app", "styled-system"]
}