chore(release): prepare Linaria 8 for WyW 2

Author: Anber

.changeset/wyw-alpha-static-eval.md

@@ -1,8 +1,21 @@
 ---
-"@linaria/atomic": patch
-"@linaria/core": patch
-"@linaria/react": patch
-"@linaria/stylelint": patch
+"@linaria/atomic": major
+"@linaria/core": major
+"@linaria/babel-plugin-interop": major
+"linaria": major
+"@linaria/postcss-linaria": major
+"@linaria/react": major
+"@linaria/server": major
+"@linaria/stylelint-config-standard-linaria": major
+"@linaria/stylelint": major
 ---
 
-Migrate WyW dependencies to 2.0.0-alpha.1 and expose processor static evaluation semantics for the new evaluator architecture.
+Release Linaria 8 with WyW 2.0.0 stable dependencies and Node.js 22+ support.
+
+Linaria processors now expose WyW 2 static evaluation semantics, allowing the default `eval.strategy: "hybrid"` mode to resolve statically provable values before falling back to the evaluator. This keeps existing dynamic/runtime-only interpolation support while reducing evaluator work for values that can be resolved from static bindings and imports.
+
+Migration notes:
+
+- Node.js 22 or newer is required.
+- 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 fallback, or use `static` to reject evaluator fallback.
+- CSS rule emission order may change for cascade ties with identical specificity because WyW 2 uses the Oxc/static-first pipeline and can preserve/process imports differently. Make precedence explicit with selector specificity, composition, or source structure where order matters.

.github/workflows/check.yml

@@ -18,10 +18,10 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        node-version: [20.x, 22.x]
+        node-version: [22.x, 24.x]
         include:
           - os: windows-latest
-            node-version: 20.x
+            node-version: 22.x
 
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -51,10 +51,10 @@ jobs:
       - name: Install and prepare
         run: pnpm install --frozen-lockfile --strict-peer-dependencies
       - name: ESLint
-        if: matrix.os == 'ubuntu-latest' && matrix.node-version == '20.x'
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == '22.x'
         run: pnpm lint
       - name: TSLint
-        if: matrix.os == 'ubuntu-latest' && matrix.node-version == '20.x'
+        if: matrix.os == 'ubuntu-latest' && matrix.node-version == '22.x'
         run: pnpm turbo run test:dts
       - name: Tests
         run: pnpm turbo run test

.github/workflows/release.yml

@@ -26,10 +26,10 @@ jobs:
           version: 9
           run_install: false
 
-      - name: Setup Node.js 20.x
+      - name: Setup Node.js 22.x
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          node-version: 20.x
+          node-version: 22.x
           registry-url: 'https://registry.npmjs.org'
 
       - name: Upgrade npm for trusted publishing (OIDC)

.github/workflows/site-deploy.yml

@@ -19,10 +19,10 @@ jobs:
           version: 9
           run_install: false
 
-      - name: Use Node.js 20.x
+      - name: Use Node.js 22.x
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          node-version: 20.x
+          node-version: 22.x
 
       - name: Install and prepare
         run: pnpm install --frozen-lockfile --strict-peer-dependencies

README.md

@@ -65,7 +65,9 @@ See [Configuration](https://wyw-in-js.dev/configuration) to customize how Linari
 
 Linaria relies on WyW (`@wyw-in-js/*`) to evaluate your modules at build time and extract CSS. If you hit issues like slow builds, invalidation storms, or unexpected code being executed during the build, it’s usually related to the WyW evaluation model and how your modules are structured.
 
-Linaria 7 requires Node.js `>=20` (WyW 1.x enforces this via `engines`).
+Linaria 8 requires Node.js `>=22` (WyW 2.x enforces this via `engines`). WyW 2 defaults to `eval.strategy: "hybrid"`, so statically provable values are resolved before falling back to the evaluator for dynamic values.
+
+If your build depends on evaluator-only side effects or exact CSS rule order ties, review the Linaria 8 migration notes in [docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md).
 
 See https://wyw-in-js.dev/stability for practical guidance and common pitfalls.
 

docs/CONFIGURATION.md

@@ -11,16 +11,22 @@ Example `wyw-in-js.config.js`:
 
 ```js
 module.exports = {
-  evaluate: true,
+  eval: {
+    strategy: 'hybrid',
+  },
   displayName: false,
 };
 ```
 
 ## Options
 
-- `evaluate: boolean` (default: `true`):
+- `eval.strategy: "hybrid" | "execute" | "static"` (default: `"hybrid"`):
+
+  Controls how WyW resolves values used in CSS interpolations. The recommended default, `"hybrid"`, uses static-first resolution: WyW first tries to prove values from Linaria processor static semantics, `staticBindings`, and statically resolvable imports, then falls back to the evaluator for values that cannot be proven statically.
 
-  Enabling this will evaluate dynamic expressions in the CSS. You need to enable this if you want to use imported variables in the CSS or interpolate other components. Enabling this also ensures that your styled components wrapping other styled components will have the correct specificity and override styles properly.
+  Use `"execute"` when you need evaluator-only compatibility, for example while migrating code that relies on build-time side effects or exact import execution order. Use `"static"` as a strict validation mode when fallback to the evaluator should be rejected. The older top-level `evaluate` option should be migrated to `eval.strategy` in Linaria 8 / WyW 2.
+
+  Evaluated values are included in the generated CSS. Since fallback evaluation runs at build time in Node.js, avoid browser-only APIs, unavailable runtime globals, Node native modules such as `fs`, and side effects in evaluated expressions.
 
 - `displayName: boolean` (default: `false`):
 
@@ -445,7 +451,9 @@ module.exports = {
     [
       '@linaria',
       {
-        evaluate: true,
+        eval: {
+          strategy: 'hybrid',
+        },
         displayName: process.env.NODE_ENV !== 'production',
       },
     ],

docs/HOW_IT_WORKS.md

@@ -148,7 +148,7 @@ const Container = styled.h1`
 
 We support this usage because it allows you to use a library such as [polished.js](https://polished.js.org) which outputs object based styles along with Linaria.
 
-If you've configured the plugin to evaluate expressions with `evaluate: true` (default), any dynamic expressions we encounter will be evaluated during the build-time in a sandbox, and the result will be included in the CSS. Since these expressions are evaluated at build time in Node, you cannot use any browser specific APIs or any API which is only available in runtime. Access to Node native modules such as `fs` is also not allowed inside the sandbox to prevent malicious scripts. In addition, to achieve consistent build output, you should also avoid doing any side effects in these expressions and keep them pure.
+By default, Linaria uses WyW's `eval.strategy: "hybrid"` mode. WyW first tries to resolve values statically from Linaria processor metadata, `staticBindings`, and statically resolvable imports. If a value cannot be proven statically, WyW falls back to build-time evaluation and includes the result in the generated CSS. Since fallback evaluation runs in Node.js, you cannot use browser-specific APIs, runtime-only globals, or Node native modules such as `fs`. To keep build output consistent, avoid side effects in evaluated expressions and keep them pure.
 
 You might want to skip evaluating a certain interpolation if you're using a browser API, a global variable which is only available at runtime, or a module which breaks when evaluating in the sandbox for some reason. To skip evaluating an interpolation, you can always wrap it in a function, like so:
 
@@ -162,13 +162,13 @@ But keep in mind that if you're doing SSR for your app, this won't work with SSR
 
 ### Evaluators
 
-Linaria can use different strategies for evaluating the interpolated values.
-Currently, we have two built-in strategies:
+Linaria relies on WyW strategies for resolving interpolated values:
 
-- `extractor` was the default strategy in `1.x` version. It takes an interpolated expression, finds all the referenced identifiers, gets all its declarations, repeats cycle for all identifiers in found declarations, and then constructs a new tree of statements from all found declarations. It's a pretty simple strategy, but it significantly changes an evaluated code and doesn't work for non-primitive js-constructions.
-- `shaker` was introduced as an option in `1.4` and became the default in `2.0` version. In contrast to `extractor`, `shaker` tries to find all irrelevant code and cuts it out of the file. As a result, interpolated values can be defined without any restrictions.
+- `hybrid` is the default in Linaria 8 / WyW 2. It resolves statically provable values without starting the evaluator, then falls back to evaluator execution for unresolved dynamic values.
+- `execute` uses evaluator-only behavior and is the compatibility escape hatch for projects that depend on build-time side effects or exact import execution order.
+- `static` is a strict validation mode that rejects fallback to evaluator execution.
 
-If an interpolated value or one of its dependencies is imported from another module, that module will be also processed with an evaluator (the implementation of evaluator will be chosen by matching `rules` from [the Linaria config](./CONFIGURATION.md#options)).
+If an interpolated value or one of its dependencies is imported from another module, WyW processes that module according to the configured strategy. In `hybrid` mode, the imported value may be resolved statically; otherwise WyW falls back to the evaluator selected by matching `rules` from [the Linaria config](./CONFIGURATION.md#options).
 
 Sometimes it can be useful to implement your own strategy (it can be just a mocked version of some heavy or browser-only library). You can do it by implementing `Evaluator` function:
 

docs/MIGRATION_GUIDE.md

@@ -1,5 +1,32 @@
 # Migration Guide
 
+# 8.x from 7.x
+
+## For Users
+
+Linaria 8 updates the WyW toolchain (`@wyw-in-js/*`) to `2.0.0` stable. 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+ (aligned with WyW 2.x `engines`).
+- 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.
+- 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

examples/astro-solid/package.json

@@ -8,7 +8,7 @@
     "@astrojs/solid-js": "^1.2.3",
     "@babel/core": "^7.23.5",
     "@linaria/core": "workspace:^",
-    "@wyw-in-js/vite": "2.0.0-alpha.1",
+    "@wyw-in-js/vite": "2.0.0",
     "astro": "^1.6.10",
     "solid-js": "^1.6.2",
     "vite": "^3",

examples/esbuild/package.json

@@ -7,7 +7,7 @@
     "linaria-website": "workspace:^"
   },
   "devDependencies": {
-    "@wyw-in-js/esbuild": "2.0.0-alpha.1",
+    "@wyw-in-js/esbuild": "2.0.0",
     "esbuild": "^0.15.16"
   },
   "scripts": {