---
title: Using Next.js
description: Easily use Bamboo with Next.js with our dedicated integration.
---

If you don't have Next.js app installed, you can follow the [Start a new project](#start-a-new-project) section to
create a new Next.js app, otherwise you can skip to the [Install Bamboo CSS](#install-bamboo-css) section.

<RouteSwitch values={["app-dir","pages-dir"]}>

## Start a new project

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

<RouteSwitchTrigger values={['Using App Router', 'Using Pages Router']} />

  <Steps>
  ### Create a Next.js app

First, create a Next.js app using the official [Create Next App](https://nextjs.org/docs/api-reference/create-next-app)
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.

  <Tabs items={['pnpm', 'npm', 'yarn', 'bun']} variant="code">
    {/* <!-- prettier-ignore-start --> */}
    <Tab>
      ```bash
      pnpm dlx create-next-app@latest --use-pnpm
      ```
    </Tab>
    <Tab>
      ```bash
      npx create-next-app@latest --use-npm
      ```
    </Tab>
    <Tab>
      ```bash
      yarn dlx create-next-app@latest --use-yarn
      ```
    </Tab>
    <Tab>
      ```bash
      bunx create next-app@latest --use-bun
      ```
    </Tab>
    {/* <!-- prettier-ignore-end --> */}
  </Tabs>

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

  <RouteSwitchContent value="app-dir">
  {/* <!-- prettier-ignore-start --> */}
    ```bash
    ✔ 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
    ```
  {/* <!-- prettier-ignore-end --> */}
  </RouteSwitchContent>
  <RouteSwitchContent value="pages-dir">
  {/* <!-- prettier-ignore-start --> */}
    ```bash
    ✔ 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)? … No
    ✔ Would you like to customize the default import alias? … No
    ```
  {/* <!-- prettier-ignore-end --> */}
  </RouteSwitchContent>

Enter the newly created directory:

```bash
cd test-app
```

### Install Bamboo CSS

Install Bamboo CSS dependency using your favorite package manager.

  <Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
  {/* <!-- prettier-ignore-start --> */}
    <Tab>
      ```bash
      pnpm install -D @bamboocss/dev
      pnpm bamboo init --postcss
      ```
    </Tab>
    <Tab>
      ```bash
      npm install -D @bamboocss/dev
      npx bamboo init --postcss
      ```
    </Tab>
    <Tab>
      ```bash
      yarn add -D @bamboocss/dev
      yarn bamboo init --postcss
      ```
    </Tab>
    <Tab>
      ```bash
      bun add -D @bamboocss/dev
      bun bamboo init --postcss
      ```
    </Tab>
  {/* <!-- prettier-ignore-end --> */}
  </Tabs>

`bamboo init --postcss` creates a `postcss.config.cjs` file at the root of your project with the following code:

```js {3}
module.exports = {
  plugins: {
    '@bamboocss/dev/postcss': {},
  },
}
```

For advanced configuration follow the Next.js PostCSS guide to set up a custom PostCSS configuration by referring to
this [link](https://nextjs.org/docs/pages/building-your-application/configuring/post-css#customizing-plugins).

### Update package.json scripts

Add `"prepare": "bamboo codegen"` to `scripts`. It runs [codegen](/docs/references/cli#codegen) after every dependency
install, so the output directory can stay in `.gitignore`.

### Configure the content

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

<RouteSwitchContent value="app-dir">

```ts {7} filename="bamboo.config.ts"
import { defineConfig } from '@bamboocss/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',
})
```

</RouteSwitchContent>

<RouteSwitchContent value="pages-dir">

```ts {7} filename="bamboo.config.ts"
import { defineConfig } from '@bamboocss/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/pages/**/*.{ts,tsx,js,jsx}'],
  // Files to exclude
  exclude: [],
  // The output directory for your css system
  outdir: 'styled-system',
})
```

</RouteSwitchContent>

### Configure the entry CSS with layers

<RouteSwitchContent value="app-dir">
  In your Next.js project, navigate to the `src/app` folder and open `globals.css` file. Replace all the content with
  the following code:
</RouteSwitchContent>
<RouteSwitchContent value="pages-dir">
  In your Next.js project, navigate to the `src/styles` folder and open `globals.css` file. Replace all the content with
  the following code:
</RouteSwitchContent>

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

<RouteSwitchContent value="app-dir">
  
  > **Note:** Feel free to remove the `page.module.css` file as we don't need it
  anymore.
  
</RouteSwitchContent>
<RouteSwitchContent value="pages-dir">

> **Note:** Feel free to remove the `Home.module.css` file as we don't need it anymore.

</RouteSwitchContent>

### Import the entry CSS in your app

<RouteSwitchContent value="app-dir">
  
Make sure that you import the `globals.css` file in your `src/app/layout.tsx` file as follows:

```tsx {1} filename="./src/app/layout.tsx"
import './globals.css'
```

</RouteSwitchContent>
<RouteSwitchContent value="pages-dir">

Make sure that you import the `globals.css` file in your `src/pages/_app.tsx` file as follows:

```tsx {1} filename="./src/pages/_app.tsx"
import '../styles/globals.css'
import type { AppProps } from 'next/app'

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

</RouteSwitchContent>

### Start using Bamboo

<RouteSwitchContent value="app-dir">
  We will update the contents of `src/app/page.tsx` with the following snippet that uses Bamboo CSS:
</RouteSwitchContent>
<RouteSwitchContent value="pages-dir">
  We will update the contents of `src/pages/index.tsx` with the following snippet that uses Bamboo CSS:
</RouteSwitchContent>

```tsx
import { css } from '../../styled-system/css'

export default function Home() {
  return <div className={css({ fontSize: '2xl', fontWeight: 'bold' })}>Hello 🎋!</div>
}
```

### Start the development server

Start the dev server with `pnpm dev`, then open [http://localhost:3000](http://localhost:3000).

</Steps>
</RouteSwitch>

## 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:

```diff {3,4}
{
"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:

- [vercel/next.js#39410](https://github.com/vercel/next.js/issues/39410)
- [vercel/next.js#48748](https://github.com/vercel/next.js/issues/48748)
- [vercel/next.js#47533](https://github.com/vercel/next.js/issues/47533)

### I don't see any import autocomplete in my IDE

Add the `styled-system` directory to `include` in `tsconfig.json`. See
[the CLI guide](/docs/installation/cli#troubleshooting).

### 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:

```json filename="tsconfig.json"
{
  "compilerOptions": {
    "target": "es6"
  }
}
```
