next-yak

next-yak provides first-class support for the following environments:

• Next.js: Supports both Webpack and Turbopack.
• Vite: Supports Vite 7+ (including Vite 8 with OXC/Rolldown) since v9.1.0. This includes any Vite-based framework like react-router or tanstack start.
• Storybook: Supports Storybook 10+ with both Vite and Webpack builders via the storybook-addon-yak addon.

Next-Yak is evaluated against other styling approaches based on several performance and developer experience metrics. When choosing a styling solution, consider the following trade-offs:

• Input Delay: Injecting styles during streaming or render can cause long delays on low-end devices due to style invalidations.
• Zero Runtime: The absence of code for CSSOM insertions or updates.
• Zero SSR Overhead: The absence of code generating CSS during Server-Side Rendering.
• Compile time optimization: Minimizing compile time (e.g., by using Rust).
• Ecosystem Support: Next-Yak supports Vite (since v9.1.0) and Storybook (via storybook-addon-yak).

The next-yak architecture is divided into three main parts that work together to provide a zero-runtime-overhead (mostly) styling experience:

1. The Compile Time Part: Consists of a Rust-based SWC plugin and a bundler-specific loader. The SWC plugin extracts styles from tagged template literals (like styled and css) and transforms code to use next-yak runtime functions. The loader then resolves dependencies and delivers the extracted CSS through the bundler's native pipeline.
2. The Runtime Part: A minimal set of functions responsible for merging class names and handling dynamic styles (like CSS variables) at runtime.
3. Optional Context: A theme provider for managing context-based styling.

next-yak supports three bundler backends: webpack (Next.js), Turbopack (Next.js), and Vite.

By default, next-yak performs folding (controlled by the foldStatic option). This optimizes your JSX at build time by inlining the styled component directly into the HTML element.

For example, <Button> is compiled into a plain <button> with a generated className. Because the component is inlined, it no longer exists in the React tree, meaning it will not appear in React DevTools or component stacks. This behavior is consistent in both development and production.

next-yak is a zero-runtime CSS-in-JS library designed for high performance and compatibility with React Server Components (RSC). It achieves this through a two-part architecture:

1. Static Analysis: At build time, next-yak parses your styles and generates standard CSS-Modules files. This allows the bundler's native CSS tool (like PostCSS for Webpack or Lightning CSS for Turbopack/Vite) to optimize the CSS.
2. Runtime: To support dynamic styling (e.g., styles based on props), a lightweight runtime is used. It manages generated class names and modifies them based on the provided props at runtime.

This approach provides the benefits of static CSS (no processing during hydration, support for 103 early hints) while maintaining the developer experience of dynamic CSS-in-JS.

Mixins are declarations of the css utility function that can be stored in variables and reused within styled declarations. They can be static or dynamic (accepting props).

Static Mixin:

const mixin = css`color: green;`;
const MyComp = styled.div`background-color: yellow; ${mixin}`;

Dynamic Mixin (using props):

const mixin = css`color: ${(props) => (props.$green ? "green" : "blue")};`;
const MyComp = styled.div`background-color: yellow; ${mixin}`;

During build time, css literals are converted into class names or CSS variables to optimize performance.

import { css, styled } from 'next-yak';

const mixin = css`
  color: ${(props) => (props.$green ? "green" : "blue")};
`;

const MyComp = styled.div`
  background-color: yellow;
  ${mixin}
`;

The yak/style-conditions rule warns when arrow functions inside styled/css literals return static values that would result in unnecessary or invalid CSS variables.

next-yak uses two primary methods for dynamic styling:

1. Class-based Dynamic Styles: Used for binary conditions or fixed variations. Styles are pre-compiled into separate CSS classes that are toggled at runtime. This is highly efficient.
2. CSS Variables: Used for truly dynamic values (e.g., user inputs, animation states, calculated positions). Values are extracted into CSS custom properties and set via inline styles at runtime.

The rule helps you avoid using the CSS variable approach for values that could have been handled more efficiently via the class-based approach.

When you use a function inside a styled template literal to return a value for an existing property, next-yak automatically transforms these into CSS variables during build time. This ensures dynamic values are handled efficiently via the style attribute without interfering with other CSS variables.

Example:

const Box = styled.div<{ $variant: "primary" | "secondary", $color: string }>`
  font-size: ${props => props.$variant === "primary" ? "2rem" : "1rem" };
  color: ${props => props.$color};
  display: flex;
`;

This is transformed into a component that uses var(--var1) and var(--var2) internally.

import { styled } from 'next-yak';

const Box = styled.div<{ $variant: "primary" | "secondary", $color: string }>`
  font-size: ${props => props.$variant === "primary" ? "2rem" : "1rem" };
  color: ${props => props.$color};
  display: flex;
`;