@salty-css/webpack weekly downloads statistics

Salty CSS — CSS-in-JS that compiles away

Salty CSS is a build-time, type-safe CSS-in-JS library. You author styles in .css.ts files; the compiler emits real CSS, your runtime ships zero styling logic.

Get started · API index · Docs · Discord · GitHub · NPM

Features

• Build-time compilation — no runtime style injection, no FOUC, no client bundle cost. • Framework support — Next.js (App + Pages, React Server Components, Webpack & Turbopack), React + Vite, React + Webpack, Astro. • Type safety — TypeScript-first authoring, generated token types, an ESLint plugin. • Design tokens & theming — static, responsive (media-bound), and conditional (data-attribute / class-bound) variables in one place. • Templates — reusable style bundles with their own variants. • Modifiers — custom value transformers ('space:3' → '12px') defined in config. • Variants, compound variants, anyOf variants, default variants out of the box.

Get started

init detects your framework, installs the right packages, creates salty.config.ts, and wires the bundler plugin. Per-framework setup:

• Next.js → salty-css.dev/docs/installation — withSaltyCss(nextConfig) in next.config.ts. Auto-detects Webpack vs Turbopack; React Server Components supported. • React + Vite → salty-css.dev/docs/installation — saltyPlugin(__dirname) in vite.config.ts. • Astro → salty-css.dev/docs/installation — saltyIntegration() in astro.config.mjs.

React + Webpack (without Next.js) is also supported via @salty-css/webpack.

CLI

| Command | Alias | What it does |

| npx salty-css init [directory] | — | Detect framework, install packages, create salty.config.ts, wire the plugin. | | npx salty-css generate [filePath] | g | Scaffold a new Salty component file. Flags: --name, --className, --tag. | | npx salty-css build [directory] | b | Compile *.css.ts files into saltygen/index.css. Not needed when the bundler plugin is running. Flags: --watch, --mode. | | npx salty-css update [version] | up | Update all @salty-css/* packages. Defaults to latest. Flags: --dir, --yes. | | npx salty-css --version | — | Print CLI version. |

Full reference: salty-css.dev/docs/cli.

Good to know

1. File extensions matter. styled, className, keyframes, and every defineX(...) call must live in a file ending .css.ts, .css.tsx, .salty.ts, .styles.ts, or .styled.ts. The compiler ignores everything else. 2. Extending non-Salty components is fine — styled(NextLink, { ... }) — as long as the wrapped component forwards className to a DOM element. 3. Async values & functions are allowed (base: { color: async () => 'red' }), but heavy imports inside *.css.ts slow the build. 4. React Server Components are supported via @salty-css/next — no 'use client' needed for styled output.

ESLint

Salty CSS ships a small ESLint plugin and matching shareable config. Two rules, both error by default, both autofixable, both scoped to Salty files (.css.ts, .css.tsx, .salty.ts, .styles.ts, .styled.ts):

• @salty-css/core/must-be-exported — every styled, className, keyframes, and defineX* call must be exported; the compiler ignores anything else. • @salty-css/core/no-variants-in-base — variants must be a sibling of base, not nested inside it.

Flat config (ESLint 9+):

Legacy (.eslintrc):

Full reference → salty-css.dev/docs/eslint.

API index

| Symbol | Import | One-liner | Docs |

| styled | @salty-css/react/styled | React component factory with variants & extension. | api/styled | | className | @salty-css/react/class-name | CSS class string with .variant() chaining. | api/classname | | Variants | — | variants, compoundVariants, anyOfVariants, defaultVariants semantics. | variants | | Overrides | — | Extend components, swap element, override per-instance via style. | overrides | | ESLint plugin | @salty-css/eslint-config-core | Two rules: enforce export and correct variants placement on Salty files. | eslint | | defineConfig | @salty-css/core/config | Top-level project config. | api/config | | defineVariables | @salty-css/core/factories | Static, responsive, and conditional CSS variables (tokens). | variables | | Theming | — | data-theme switcher built on conditional variables. | theming | | defineGlobalStyles | @salty-css/core/factories | Global rules (html, body, etc.). | api/define-factories | | defineMediaQuery | @salty-css/core/factories | Named, reusable media queries. | media-queries | | defineTemplates | @salty-css/core/factories | Reusable style bundles, optionally with variants. | templates | | defineFont | @salty-css/core/factories | @font-face (or @import) + CSS variable in one. | fonts | | defineImport | @salty-css/core/factories | Pull external CSS into Salty's imports layer. | imports | | keyframes | @salty-css/react/keyframes | Typed @keyframes with params and initial-state injection. | animations | | defineViewportClamp | @salty-css/core/helpers | Fluid clamp() values that scale with the viewport. | viewport-clamp | | color | @salty-css/core/helpers | Color manipulation (alpha, darken, …). | color-function | | Modifiers | (on defineConfig) | Custom value transformers, e.g. 'space:3' → '12px'. | modifiers | | withSaltyCss | @salty-css/next | Next.js config wrapper (Webpack + Turbopack). | installation | | saltyPlugin (Vite) | @salty-css/vite | Vite plugin. | installation | | saltyPlugin (Webpack) | @salty-css/webpack | Webpack loader + plugin. | installation | | saltyIntegration | @salty-css/astro/integration | Astro integration. | installation |

styled

See full reference → salty-css.dev/docs/api/styled.

className

Framework-agnostic class-string factory. The return value is a string you can drop in className=, plus a .variant(name, value) method for chaining variant classes.

See full reference → salty-css.dev/docs/api/classname.

Variants

styled and className share the same variant shape:…

Description from the npm listing.