Skip to content

MIGRATION_GUIDE.md

Latest commit

 

History

History
128 lines (86 loc) · 6.55 KB

MIGRATION_GUIDE.md

File metadata and controls

128 lines (86 loc) · 6.55 KB

Migration Guide

8.x from 7.x

For Users

Linaria 8 updates the WyW toolchain (@wyw-in-js/*) to 2.x stable releases. This is a major release because WyW 2 changes the build-time evaluation pipeline and raises the minimum Node.js version.

  • Linaria 8 requires Node.js 22.12+ (aligned with the WyW 2 / Oxc dependency graph).
  • The default evaluation mode is WyW's eval.strategy: "hybrid". It resolves statically provable values first using Linaria processor static semantics, staticBindings, and statically resolvable imports, then falls back to the evaluator for values that cannot be proven statically.
  • Top-level evaluate config should be migrated to eval.strategy. Use execute for evaluator-only compatibility, keep the default hybrid for static-first resolution with evaluator fallback, or use static to reject evaluator fallback.
  • Babel config and Babel resolver plugins are no longer used as an implicit module-resolution fallback during WyW evaluation. If evaluated code imports aliased specifiers, move those aliases to WyW configuration with eval.customResolver, eval.resolver, or staticBindings.
  • If your project relies on build-time side effects or on the exact order in which evaluated imports execute, compare the generated CSS/JS output after upgrading and use eval.strategy: "execute" where evaluator-only behavior is required.
  • CSS rule emission order can change for cascade ties with identical specificity. WyW 2 uses the Oxc/static-first pipeline and can preserve or process imports differently, so make precedence explicit through selector specificity, composition, or source structure where order matters.
  • Review https://wyw-in-js.dev/migration/v2 and https://wyw-in-js.dev/stability for the WyW 2 evaluation model, debugging notes, and performance guidance.

Example evaluator-only compatibility config:

module.exports = {
  eval: {
    strategy: 'execute',
  },
};

For Custom Processor Developers

Linaria processors now expose WyW 2 static evaluation semantics. Custom processors that integrate with WyW's static-first path should implement the optional static processor contract in @wyw-in-js/processor-utils; unresolved values can still fall back to the evaluator in hybrid mode.

7.x from 6.x

For Users

Linaria 7 updates the WyW toolchain (@wyw-in-js/*) to ^1.0.0 (stable). This affects build-time evaluation (CSS extraction) and can surface previously hidden issues in evaluated modules.

  • Review https://wyw-in-js.dev/stability for the evaluation model, common pitfalls, and performance guidance.
  • Linaria 7 requires Node.js 20+ (aligned with WyW 1.x).
  • If you rely on WyW cache internals, note that WyW 1.x can promote fully-statically-evaluatable modules to only: ['*'] and may re-evaluate modules when cached exports are incomplete.
  • If you import JSON from code that is evaluated by WyW, add .json to extensions and ensure .json is ignored by evaluation rules (so it's parsed as JSON, not by Babel).
  • Rollup users on WyW 1.0.6: WyW serializes transform() by default; if you hit Rollup "Unexpected early exit" (unresolved plugin promises), try serializeTransform: false in the WyW Rollup plugin config.

6.x from 5.x, 4.x, 3.x

For Users

The main breaking change is that all tooling has been moved from the @linaria scope to the @wyw-in-js scope. This means that you will need to update your dependencies as follows:

Old New
@linaria/babel-preset @wyw-in-js/babel-preset
@linaria/cli @wyw-in-js/cli
@linaria/esbuild @wyw-in-js/esbuild
@linaria/rollup @wyw-in-js/rollup
@linaria/shaker discontinued
@linaria/vite @wyw-in-js/vite
@linaria/webpack4-loader discontinued
@linaria/webpack5-loader @wyw-in-js/webpack-loader

There is no longer a need to install @linaria/shaker as it is now part of @wyw-in-js/transform, which will be installed automatically with the bundler plugins.

The configuration file has been renamed from linaria.config.js (linariarc) to wyw-in-js.config.js (.wyw-in-jsrc).

For Custom Processor Developers

Base classes for processors and most helpers have been moved to @wyw-in-js/processor-utils.

All APIs that had linaria in their names have been renamed:

  • The field that stores meta information in runtime has been renamed from __linaria to __wyw_meta
  • The export with all interpolated values has been renamed from __linariaPreval to __wywPreval
  • The caller name in Babel has been renamed from linaria to wyw-in-js

For additional information, please visit the wyw-in-js.dev.

4.x, 3.x from 2.x

This release was mostly a refactor to split into more packages.

Breaking changes

All these package imports in code need to be updated:

Old New
linaria @linaria/core
linaria/loader @linaria/webpack4-loader, @linaria/webpack5-loader
linaria/react @linaria/react
linaria/rollup @linaria/rollup
linaria/server @linaria/server
linaria/stylelint-config @linaria/stylelint

The shaker evaluator has moved from linaria/evaluators into its own package. You'll need to add @linaria/shaker to your package.json even if you never import it.

The Babel preset moved from linaria/babel to @linaria/babel-preset but has to be referenced as @linaria in a Babel config. See #704

In package.json import all the new packages you use.

2.x from 1.x

Breaking changes

Core-js dependency removal and theoretical drop compatibility for node below 10

In #569 We removed core-js dependency.

It should not effectively affect your users or build pipelines. But it was technically a breaking change.

We set babel preset that makes all non-browser dependencies compatible with node from version 10. But previous setup was using browser env so If you was able to build Linaria with previous versions of node, it should work also now. Support for browsers environment didn't change.

After that you should be able to solve issues with core-js dependency in your project, because it will no longer collide with version used by Linaria.

The default evaluation strategy has been changed to shaker

It should not affect existed code since the new strategy is more powerful, but you can always switch to the old one by adding the next rules section to your Linaria-config:

  [
    {
      action: require('linaria/evaluators').extractor,
    },
    {
      test: /\/node_modules\//,
      action: 'ignore',
    },
  ]