Add @salty-css/astro Integration to astro.config.mjs — Compile Styles on Every Build With Zero Client Cost

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 Astro, run:

npm i @salty-css/astro

Astro

1. In your existing Astro 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 in any .astro page or layout and see it working!

Manual configuration

1. Install the Astro integration:

   npm i @salty-css/astro

2. Create salty.config.ts in your project root.

3. Add the Salty CSS integration to astro.config.mjs:

   import { defineConfig } from "astro/config";
   import saltyIntegration from "@salty-css/astro/integration";
   
   export default defineConfig({
     integrations: [saltyIntegration()],
   });

   saltyIntegration accepts { srcDir?: string; rootDir?: string }. srcDir defaults to 'src'; rootDir defaults to the Astro config root.

4. Make sure that salty.config.ts and astro.config.mjs 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 your global stylesheet: @import 'insert_path_to_index_css';.

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/astro/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.