# 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:

```js
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](https://wyw-in-js.dev).

# 4.x, 3.x from 2.x

This release was mostly a refactor to [split into more packages](https://github.com/callstack/linaria/pull/687/).

## 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 https://github.com/callstack/linaria/issues/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](https://github.com/callstack/linaria/pull/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](./HOW_IT_WORKS.md#evaluators) 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:
```js
  [
    {
      action: require('linaria/evaluators').extractor,
    },
    {
      test: /\/node_modules\//,
      action: 'ignore',
    },
  ]
```