Using Sugarcube with Next.js

This guide covers how to use Sugarcube with Next.js projects. For a complete introduction to Sugarcube, including initialization and basic usage, see our quick start guide and using Sugarcube documentation.

1. Initialize Sugarcube in your project:

pnpm dlx make-sugarcube@latest init

npx make-sugarcube@latest init

yarn make-sugarcube@latest init

bunx --bun make-sugarcube@latest init

2. Import your generated CSS in your Next.js app:

import '@/styles/global/variables/tokens.variables.css'

TODO: Add a note about the cascade layers and how to use them.

ATTENTION: You must use postcss-import to import your generated CSS because Next.js doesn’t support CSS imports with cascade layers.

module.exports = {
    plugins: {
        "postcss-import": {},
    },
};

## Optional Plugin

For the best development experience, we recommend using our PostCSS plugin. This will automatically regenerate your CSS when you make changes to your design tokens.

<PackageManagerTabs command="npm install @sugarcube-org/postcss" />

Add to your PostCSS config:

```js title="postcss.config.js"
const config = {
    plugins: {
        "@sugarcube-org/postcss": {},
    },
};

export default config;

Now you can use your token-generated CSS variables in your Next.js components:

export default function Card() {
  return (
    <div className="card">
      <h2 style={{ color: 'var(--text-primary)' }}>Hello World</h2>
      <p style={{ backgroundColor: 'var(--surface-primary)' }}>
        This is using Sugarcube tokens!
      </p>
    </div>
  )
}

Try changing a value in your token files - with the plugin installed, you’ll see the changes instantly in your browser!

The PostCSS plugin supports the following options:

require('@sugarcube-org/postcss')({
  // Whether to suppress success messages
  silent: false,

  // Whether to only validate tokens without generating CSS
  validateOnly: false,

  // Whether to check if files are in sync
  checkSync: false
})