# Salty CSS for Next.js > Salty CSS served fresh from the App Router — zero-runtime styles that work with React Server Components. This file contains the Salty CSS documentation for the Next.js framework, extracted for LLM ingestion. Includes framework-specific docs, shared concepts, and Next.js-compatible recipes. Source: https://salty-css.dev/llms-full-next.txt — Generated: 2026-06-23 Full file (all frameworks): https://salty-css.dev/llms-full.txt Companion index: https://salty-css.dev/llms.txt --- # Salty CSS for Next.js Source: https://salty-css.dev/next/ > Salty CSS served fresh from the App Router — zero-runtime styles that work with React Server Components. Zero-runtime styles that work with React Server Components — no client bundle tax, no hydration mismatch dance. ### Get started ```bash npx salty-css init ``` Then read the [Installation guide](/docs/next/installation/) or the [Quick Start](/docs/next/quick-start/). ### What you get **Works with React Server Components** — Zero-runtime CSS means no client bundle tax and no hydration mismatch dance. RSC, client components, App Router, Pages Router — all the same. **Webpack or Turbopack — your call** — `withSaltyCss` auto-detects which bundler your dev server is using. Same plugin, same output, on Next.js 15 and 16. **Provider-less theming** — Native CSS variables plus `data-theme` on ``. Flip themes in zero re-renders — yes, even inside Server Components. ### Three steps from install to stylesheet **Step 1 — Install both packages** Next.js needs `@salty-css/next` alongside the React runtime helpers — one command takes care of both. ```bash npx salty-css init ``` **Step 2 — Save a `*.css.ts` sibling** Co-locate styles next to the component. The same file works in Server and Client components — Salty doesn't care which. ```ts // app/components/button.css.ts import { styled } from "@salty-css/react/styled"; export const Button = styled("button", { base: { padding: "0.75rem 1.25rem", borderRadius: "6px", background: "{theme.color}", color: "white", }, }); ``` **Step 3 — Wrap your config with `withSaltyCss`** One import, one wrap — `withSaltyCss` auto-detects Webpack or Turbopack and registers the compiler. ```ts // next.config.ts import { withSaltyCss } from "@salty-css/next"; import type { NextConfig } from "next"; const nextConfig: NextConfig = { // your existing Next config… }; export default withSaltyCss(nextConfig); ``` Provider-less, zero-rerender theming across Server Components and Astro islands. ### Where to go next - [Installation](/docs/next/installation/) — Wire up `withSaltyCss` in `next.config.ts`. - [Quick Start](/docs/next/quick-start/) — From `npx salty-css init` to your first styled component. - [Component styles](/docs/next/basics/) — The full styled API and how it composes. - [Variants](/docs/next/variants/) — Prop-driven styles and compound variants. - [Templates](/docs/next/templates/) — Reusable style recipes with defineTemplates. --- # Documentation — Next.js Source: https://salty-css.dev/docs/next/ Salty CSS is a build-time CSS-in-**TS** library for React, Next.js and Astro. You author styles in `.css.ts` files, the compiler turns them into real CSS, and your runtime ships with no styling engine attached. Meow. It's a good fit when you want **typed styles, real design tokens, and theming that doesn't need a React provider** — without giving up on the developer experience of writing CSS next to your component. ### What you get - **Typed styles** — `styled("button", { ... })` returns a typed component; variants become typed props. - **Design tokens** — `defineVariables` for static, **responsive**, and **conditional** tokens (the conditional ones are how theming works). - **Theming without a provider** — flip a `data-theme` attribute on `` and every consumer of `{theme.color}` updates. - **Templates** — `defineTemplates` for reusable style bundles with their own variants. - **Media queries that read like English** — `media.minWidth(720).and.dark`. - **Fluid sizing** — `defineViewportClamp` for `clamp()`-based values that scale with the viewport. - **Type-safe class names** — `className({ ... })` when you want the styles without the component wrapper. - **A CLI** — `npx salty-css init` / `generate` / `build` / `up` for the boring bits. ### TL;DR — install it Inside any React, Next.js or Astro project: ```bash npx salty-css init ``` Then create a component in a `*.css.ts` file: ```ts // /components/my-button.css.ts import { styled } from "@salty-css/react/styled"; export const Button = styled("button", { base: { padding: "0.75rem 1.25rem", borderRadius: "6px", background: "{theme.color}", color: "{theme.background}", }, }); ``` …and use it like any other . ### Where to go next - **New here?** → [Quick Start](/docs/quick-start/) walks you from `init` to a themed component with variants in about 15 minutes. - **Adding it to a project?** → [Installation](/docs/installation/) covers the per-framework wiring. - **Need the reference?** → [`styled`](/docs/api/styled/), [`className`](/docs/api/classname/), [`defineConfig`](/docs/api/config/). ### Search the docs Hit `Ctrl + K` (or `⌘ + K` on macOS) anywhere in the docs to open the search modal — or click **Search** at the top of the sidebar. Matching is fuzzy: partial terms like `variant`, `media` or `clamp` are usually enough. ### What's in the docs #### Getting Started - [Quick Start](/docs/quick-start/) — install, your first component, variants, theming, fonts. - [Installation](/docs/installation/) — per-framework setup (Next.js, Vite, Webpack, Astro). - [Usage](/docs/usage/) — file suffixes, dev-time naming, DevTools. - [Troubleshooting](/docs/troubleshooting/) — the fix list for the most common issues. - [CLI](/docs/cli/) — use Salty CSS from the command line. - [FAQ](/docs/faq/) — short answers to the things people ask first. #### Styling - [Component styles](/docs/basics/) — `styled`, `className`, and where each one fits. - [Variables](/docs/variables/) — design tokens with `defineVariables` (static, responsive, conditional). - [Theming](/docs/theming/) — dark mode and multi-theme without a provider. - [Fonts](/docs/fonts/) — `defineFont` for local files and remote stylesheets. - [Imports](/docs/imports/) — pull in external CSS with `defineImport`. - [Class styles](/docs/classnames/) — `className` for plain class-based styles. - [Variants](/docs/variants/) — prop-driven variants, compound, and `anyOfVariants`. - [Overrides](/docs/overrides/) — extend components, swap elements, forward props with `passProps`. - [Media queries](/docs/media-queries/) — media queries, container queries, breakpoints. - [Animations](/docs/animations/) — keyframes, stagger, pause/resume. - [Templates](/docs/templates/) — reusable styles with `defineTemplates`. #### Utilities - [Viewport clamp](/docs/viewport-clamp/) — fluid responsive sizing. - [Color function](/docs/color-function/) — manipulate colors at build time. - [Modifiers](/docs/modifiers/) — custom value transformers. #### API reference - [`styled` function](/docs/api/styled/) — full API for the `styled` component factory. - [`className` function](/docs/api/classname/) — full API for class-based styles. - [`defineConfig`](/docs/api/config/) — every option that lives in `salty.config.ts`. - [`define*` factories index](/docs/api/define-factories/) — one-page index of every factory. ### Get support Join the [Salty CSS Discord server](https://discord.gg/R6kr4KxMhP) for help, or check the [GitHub repository](https://github.com/margarita-form/salty-css) for source and issues. --- # Getting Started — Next.js Source: https://salty-css.dev/docs/next/getting-started/ Everything you need to get a Salty CSS project off the ground. Start with the **Quick Start** for a fifteen-minute end-to-end walkthrough, or jump into **Installation** if you'd rather wire the build plugin into an existing app. The remaining pages cover day-to-day **Usage**, the **CLI**, **ESLint** support, common **Troubleshooting**, and **FAQ** answers. --- # Quick Start — Next.js Source: https://salty-css.dev/docs/next/quick-start/ Goal: by the end of this page you have Salty CSS installed, a typed component on screen, prop-driven variants, dark mode that flips without a provider, and a custom font registered. Budget about 15 minutes. ### 1. Install Inside any React, Next.js, Vite, or Astro project, run: ```bash npx salty-css init ``` The CLI detects your framework, adds the right plugin (`@salty-css/next`, `@salty-css/vite`, `@salty-css/webpack`, or `@salty-css/astro`), drops a `salty.config.ts` in the project root, and wires up the build. If you'd rather wire it up yourself, see [Installation](/docs/installation/). ### 2. Your first component All Salty definitions live in files matching `*.css.ts`, `*.css.tsx`, `*.salty.ts`, `*.styled.ts`, or `*.styles.ts` — the suffix is how the compiler picks them up at build time. ```ts // /components/card.css.ts import { styled } from "@salty-css/react/styled"; export const Card = styled("section", { base: { padding: "1.5rem", borderRadius: "12px", background: "{theme.background}", color: "{theme.color}", boxShadow: "0 1px 2px rgba(0, 0, 0, 0.06)", }, }); ``` Use it like any other : ```tsx import { Component } from "./my-component.css"; const MyPage = () => { return ( This is a Salty CSS component ); }; export default MyPage; ``` Note the `{theme.background}` / `{theme.color}` tokens — we'll define those in step 4. ### 3. Add variants Variants turn props into typed style branches. Add a `size` axis and a `tone` axis: ```ts // /components/card.css.ts import { styled } from "@salty-css/react/styled"; export const Card = styled("section", { defaultVariants: { size: "medium", tone: "neutral" }, base: { padding: "1.5rem", borderRadius: "12px", background: "{theme.background}", color: "{theme.color}", }, variants: { size: { small: { padding: "1rem", borderRadius: "8px" }, medium: { padding: "1.5rem" }, large: { padding: "2.5rem", borderRadius: "16px" }, }, tone: { neutral: {}, brand: { background: "{theme.highlight}", color: "{theme.background}" }, muted: { background: "{theme.altBackground}" }, }, }, compoundVariants: [ { size: "large", tone: "brand", css: { fontWeight: 600 } }, ], }); ``` `size` and `tone` are now typed props. Render with: ```tsx import { Button } from "./button/button.css"; export const MyComponent = () => { return (

); }; ``` For more on variants — including `anyOfVariants` for "any of these branches matches" rules — see [Variants](/docs/variants/). ### 4. Add design tokens and dark mode Salty themes are CSS variables under the hood. You declare two (or more) value sets under `conditional.theme`, and the active set is picked by an attribute on an ancestor — usually ``. No provider, no context. ```ts // /styles/themes.css.ts import { defineVariables } from "@salty-css/core/factories"; export const palette = defineVariables({ colors: { ink: "#0d1117", paper: "#ffffff", sand: "#f5f1e8", coral: "#ff6b5a", }, }); export const themes = defineVariables({ conditional: { theme: { light: { background: "{colors.paper}", altBackground: "{colors.sand}", color: "{colors.ink}", highlight: "{colors.coral}", }, dark: { background: "{colors.ink}", altBackground: "#1c2128", color: "{colors.paper}", highlight: "{colors.coral}", }, }, }, }); ``` Activate a theme by setting the attribute on any ancestor — usually the root: ```html ... ``` That's the whole switch. Every `{theme.background}` / `{theme.color}` reference in your styles now reads the dark values. Flip the attribute back to `light` and it all updates again. For a working toggle that persists the choice in `localStorage` and avoids the first-paint flash: ```tsx // /components/theme-toggle.tsx "use client"; import { useEffect, useState } from "react"; type Theme = "dark" | "light"; const STORAGE_KEY = "theme"; const readInitial = (): Theme => { if (typeof window === "undefined") return "light"; const saved = window.localStorage.getItem(STORAGE_KEY) as Theme | null; if (saved === "dark" || saved === "light") return saved; return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"; }; export const ThemeToggle = () => { const [theme, setTheme] = useState("light"); useEffect(() => { const initial = readInitial(); setTheme(initial); document.documentElement.dataset.theme = initial; }, []); const toggle = () => { const next: Theme = theme === "dark" ? "light" : "dark"; setTheme(next); document.documentElement.dataset.theme = next; window.localStorage.setItem(STORAGE_KEY, next); }; return ( ); }; ``` To avoid a flash of the wrong theme on first paint in Next.js, inline a tiny pre-hydration script in `app/layout.tsx` (or `_document.tsx` for the Pages Router) so the attribute is set before React hydrates: ```tsx // /app/layout.tsx const setThemeScript = ` try { var t = localStorage.getItem("theme"); if (t !== "dark" && t !== "light") { t = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"; } document.documentElement.dataset.theme = t; } catch (e) {} `; export default function RootLayout({ children }) { return (