Linaria

Linaria is a zero-runtime CSS-in-JS library. It allows you to write styles using JavaScript/TypeScript while extracting them into static CSS files during the build process.

Key capabilities include:

• Zero Runtime: CSS is extracted to files at build time, avoiding runtime overhead.
• CSS Syntax: Supports familiar CSS syntax, including Sass-like nesting.
• Dynamic Styles: Supports dynamic prop-based styles (via React bindings) by using CSS variables under the hood.
• Logic in JS: Use standard JavaScript for styling logic instead of a separate CSS preprocessor.
• Tooling Support: Provides CSS sourcemaps for easier debugging and integrates with stylelint for linting CSS within JS files.
• Preprocessor Support: Optionally compatible with Sass or PostCSS.

Linaria uses WyW (Evaluate-on-the-fly) strategies to resolve interpolated values. Choosing the right strategy depends on your project's needs for speed vs. accuracy:

• hybrid (Default): Attempts to resolve values statically first. If a value cannot be proven statically, it falls back to build-time evaluation in a Node.js environment.
• execute: Uses evaluator-only behavior. This is a compatibility escape hatch for projects that rely on specific build-time side effects or exact import execution order.
• static: A strict mode that rejects any fallback to evaluator execution. It will fail if values cannot be resolved statically.

Warning: Because fallback evaluation runs in Node.js, you cannot use browser-specific APIs (like window) or Node native modules (like fs) inside evaluated expressions unless you wrap them in a function to skip evaluation.

The globalCache feature is enabled by default. It manages the second level of Linaria's caching system, which caches the results of the entire build process.

• Enabled (Default): Faster build processes.
• Disabled: Slower build processes, but decreased memory usage.

Linaria allows you to interpolate JavaScript values into your styles:

1. Basic Interpolations: Use variables or function calls. These are evaluated at build-time.
2. Object Interpolations: Pass a JavaScript object. Linaria converts it to a CSS string. Numeric values (e.g., minHeight: 360) will automatically have px appended if no unit is provided. Objects can contain nested selectors and media queries.

// Basic interpolation
const fontSize = 16;
const Title = styled.h1`font-size: ${fontSize}px;`;

// Object interpolation
const cover = {
  position: 'absolute',
  top: 0,
  '@media (min-width: 200px)': {
    minHeight: 480,
  },
};

const Title = styled.h1`
  font-size: 24px;
  ${cover};
`;

When using Linaria, be aware of the following constraints:

1. No IE11 support for dynamic styles: Because dynamic styles in styled components rely on CSS custom properties, they will not work in Internet Explorer 11.
2. Dynamic styles in css tag: The css tag does not support dynamic styles. For dynamic behavior, use the styled helper or alternative approaches.
3. Side-effect free modules: Any module imported into a CSS rule (e.g., a colors.js file used inside a css tag) must not have side-effects. It is recommended to keep shared configuration and helpers in files that are purely data/logic without side-effects.

To solve the 'shorthand-longhand problem' in atomic CSS, Linaria uses property priorities to ensure predictable styling.

Priority Rules:

1. Longhand vs Shorthand: Longhand properties (e.g., padding-top) have higher priority than their shorthand equivalents (e.g., padding).
2. At-rules: Declarations inside @media rules or other @-rules (like @supports) have higher priority than those outside of them.

Linaria achieves this by increasing the specificity of the rules. You can find the list of supported properties in the @linaria/atomic propertyPriority function.

Linaria supports Sass-like nesting for selectors, pseudo-elements, and pseudo-selectors using the & character to refer to the current class. It also supports nesting media queries.

Supported nesting includes:

• Pseudo-selectors: &:hover, &.className
• Pseudo-elements: &::after
• Child selectors: h3, .code
• Combinators: & + &
• Parent selectors: .parent &
• Media queries: @media (...) { ... }

const Thing = styled.div`
  color: black;

  &::after {
    content: '🌟';
  }

  h3 {
    color: tomato;
  }

  @media (min-width: 200px) {
    color: blue;
  }
`;

The happyDOM feature is enabled by default. It uses happy-dom to emulate a browser environment during the build process.

This is useful when libraries contain browser-specific code that cannot be statically evaluated by the dangerousCodeRemover. Emulating a browser allows Linaria to evaluate the code without encountering errors caused by missing browser APIs.

When using the styled helper, Linaria enables declarative dynamic styling by generating CSS variables that automatically update when component props change. This avoids the need to manually manage style updates or duplicate CSS rules for different prop values.

For example, you can define dimensions based on a size prop, and Linaria will handle the underlying CSS variable updates.

const Box = styled.div`
  background-color: orange;
  height: ${props => props.size}px;
  width: ${props => props.size}px;
`;

<Box size={48} />