Skip to main content

Migration v3 to v4

This guide covers breaking changes when migrating from chayns-toolkit v3 to v4.

Breaking Changes​

Internal Rsbuild Environments​

The toolkit now uses Rsbuild's native environments system internally. This may affect custom webpack configurations:

  • The default config structure has changed due to Rsbuild's environments approach
  • Custom webpack modifications via the webpack function in toolkit.config.ts may behave differently
  • The target parameter is no longer passed to the webpack function

Migration: If you previously used the target parameter to conditionally configure webpack, you now need to work with Rsbuild's environments. Target-specific adjustments that were previously made with if (target === 'server') should now be applied to the node environment in the generated Rsbuild config.

Alternatively, you can now specify a target property ("web" | "node" | "web-worker") per entry point in output.entryPoints, which simplifies configuration for scenarios like service workers:

// toolkit.config.ts
export default {
    output: {
        entryPoints: {
            app: {
                pathIndex: "./src/index.js",
                pathHtml: "./src/index.html",
                target: "web",
            },
            sw: {
                pathIndex: "./src/service-worker.js",
                target: "web-worker",
            },
        },
    },
}

Test your custom webpack functions thoroughly and adjust them to work with the new config structure.

Test Command Removed​

The test command has been removed from the toolkit. This command was used to run tests with Jest.

Migration: Use Vitest directly in your project instead. Vitest is the recommended alternative and offers better performance and modern features.

Webpack Public Path for SSR Projects​

Projects with Server-Side Rendering (SSR) enabled will experience a change in the __webpack_public_path__:

  • Previously, client was part of the root directory and included in the publicPath
  • Now, client is no longer part of the publicPath

Migration: If you have SSR enabled and reference remote entries, update paths like:

- ${__webpack_public_path__}v2.remoteEntry
+ ${__webpack_public_path__}client/v2.remoteEntry

This only affects projects with output.serverSideRendering enabled.

Server-Side Rendering Simplified​

The output.serverSideRendering configuration has been simplified. Previously, there were three possible values: false, true/"build-only", and "all". This caused inconsistent behavior between development and production builds.

V4 Behavior:

  • serverSideRendering: true, "build-only", and "all" are now all treated the same
  • This ensures consistent /client/ and /server/ paths between dev and build commands
  • If /client/ paths exist, /server/ bundles are always available
  • The values "all" and "build-only" are deprecated and will be removed in v5.0.0

Migration:

  export default {
    output: {
-     serverSideRendering: "all",
+     serverSideRendering: true,

-     serverSideRendering: "build-only",
+     serverSideRendering: true,
    }
  }

If you already use serverSideRendering: true, no changes are needed. However, be aware that:

  • In development, the server environment will now also be built (like in production)
  • This ensures path consistency but may slightly increase dev build times
  • If you only need client-side rendering, use serverSideRendering: false

SingleBundle Option Removed​

The singleBundle option has been removed completely. This option was already non-functional since v3.0.0.

Migration: Remove any singleBundle configuration from your toolkit.config.ts.

Development Ports Option Removed​

The development.ports option has been removed from the toolkit configuration.

Migration: Remove any development.ports configuration from your toolkit.config.ts.

New Features​

Version 4 adds support for modern tooling and configurations:

  • Linaria - Zero-runtime CSS-in-JS support (automatically enabled when installed)
  • React Compiler - Automatic React optimization (automatically enabled when installed, can be disabled via output.reactCompiler: false)
  • Entry Point Targets - Specify target per entry point in output.entryPoints (e.g., for service workers)
  • JSX Runtime - Configure React runtime mode (e.g., "automatic")
  • React Required Versions - Override required React versions for Module Federation shared dependencies via output.reactRequiredVersions

See the configuration documentation for details on these features.

Summary Checklist​

  • Test custom webpack functions (if used) - target parameter removed
  • Migrate from toolkit test to Vitest
  • Update remote entry paths if using SSR
  • Check SSR config - true/"build-only" now behave like "all" (server built in dev too)
  • Remove singleBundle config if present
  • Remove development.ports config if present