Install @salty-css/next and withSaltyCss() — Wire the App Router and output: export Without Webpack Surgery

The fastest way to start in any framework:

npx salty-css init

The init command detects your framework, installs the right packages, creates salty.config.ts, and wires the build plugin into your existing bundler config. For most projects that's all you need.

For a manual install on Next.js, run:

npm i @salty-css/next @salty-css/react

Next App Router supports RSC out of the box.

Next.js

1. In your existing Next.js repository you can run npx salty-css init to automatically configure Salty CSS.
2. Create your first Salty CSS component with npx salty-css generate [filePath] (e.g. src/custom-wrapper).
3. Import your component for example to page.tsx and see it working!

Manual configuration

1. Install the Next.js plugin and the runtime packages:

   npm i @salty-css/next @salty-css/core @salty-css/react

2. Create salty.config.ts in your app directory.
3. Wire the plugin into your Next config:
   • Next.js 15 and newer (incl. 16.2) — in next.config.ts:

     import { withSaltyCss } from "@salty-css/next";
     
     export default withSaltyCss(nextConfig);

   • Next.js 14 and older — in next.config.js:

     const { withSaltyCss } = require("@salty-css/next");
     
     module.exports = withSaltyCss(nextConfig);

4. Make sure that salty.config.ts and next.config.ts are in the same folder.
5. Build the saltygen directory by running your app once or via the CLI: npx salty-css build [directory].
6. Import global styles from saltygen/index.css in some global css file: @import 'insert_path_to_index_css';.

withSaltyCss options

Both Webpack and Turbopack are supported; withSaltyCss auto-detects which one Next.js is running (next dev --turbopack sets process.env.TURBOPACK=1) and picks the matching integration. Pass a second argument to override:

withSaltyCss(nextConfig, {
  bundler: "auto",     // 'auto' | 'webpack' | 'turbopack' — default 'auto'
  mode: undefined,     // 'production' | 'development' — defaults to NODE_ENV
  dir: undefined,      // project root for Turbopack; defaults to nextConfig.turbopack.root or process.cwd()
});

Next App Router supports RSC out of the box.

Manual setup

If salty-css init picks the wrong framework, can't find your bundler config, or you'd rather wire things up by hand, follow the manual setup for your stack. The framework-specific snippet above includes the precise commands and config edits; the steps below are the universal shape.

1. Install the packages. Each framework needs its runtime plus the core compiler:

   • Next.js: npm i @salty-css/next @salty-css/core @salty-css/react
   • React + Vite: npm i @salty-css/vite @salty-css/core @salty-css/react
   • React + Webpack: npm i @salty-css/webpack @salty-css/core @salty-css/react
   • Astro: npm i @salty-css/astro @salty-css/core

2. Wire the bundler plugin. withSaltyCss(nextConfig) for Next.js, saltyPlugin(__dirname) for Vite, saltyPlugin(config, __dirname) in webpack.config.js for Webpack, the integration for Astro.

3. Create salty.config.ts in the same directory as your bundler config (e.g. next to next.config.ts or vite.config.ts):

   import { defineConfig } from "@salty-css/react/config";
   
   export const config = defineConfig({
     // Add variables, templates, modifiers as you grow.
   });

4. Import the generated stylesheet. With the default importStrategy: 'root', Salty CSS expects one stylesheet to be imported at your app root. Most framework plugins do this for you on first run; if not, add @import "../saltygen/index.css"; (or the appropriate path) to your global CSS.

5. Build once. Run your dev server (or npx salty-css build) so saltygen/ exists before the first render.

Peer dependencies

You'll need:

The exact ranges live in each package's peerDependencies — check package.json if you're on a fringe version.

Verify your install

After running the dev server (or npx salty-css build), confirm:

1. saltygen/ exists at the root of the package you initialised. It should contain at least index.css and a salty.config.js snapshot.
2. saltygen/index.css is non-empty. A few @layer declarations and your reset should be there even before you write any components.
3. A test component renders styled. Create a *.css.ts file with a tiny styled component, use it on a page, and inspect the element in DevTools — you should see a class like s_xxxx and a matching rule in the Styles panel.
4. No build warnings about missing plugin. Salty CSS logs a warning at build time if the plugin didn't load — search your terminal output for salty-css.

If any step fails, jump to Troubleshooting.

The compiler can't warn you about two common structural mistakes: unexported styled calls, and variants accidentally nested inside base instead of alongside it. The ESLint plugin catches both — worth setting up once.