#Upgrading from 0.x to v1

This document lists all breaking changes from Rslib 0.23 to 1.0. You can use it as a migration reference.

#Upgrade Rslib to v1

Upgrade @rslib/core to version 1.0:

{
  "devDependencies": {
    "@rslib/core": "^1.0.0"
  }
}

#Rsbuild v2

Because Rslib v1 is based on Rsbuild v2, you can check the peerDependencies of the Rsbuild plugins in your project for @rsbuild/core v2 support. We recommend using Taze to upgrade the Rsbuild plugins in your project to their latest versions:

# Upgrade Rsbuild plugins in the current directory
npx taze major --include "/rsbuild/" -w

# Or recursively upgrade Rsbuild plugins across the monorepo
npx taze major --include "/rsbuild/" -w -r

If your project directly uses Rsbuild configuration or JavaScript APIs, you can refer to the Rsbuild v2 upgrade guide for the related changes.

#Default syntax target update

When output.target is 'node' and lib.syntax is not configured, Rslib v1 attempts to infer the syntax target from package.json#engines.node.

For example, the following engines.node:

{
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  }
}

Rslib resolves it to the following syntax target:

export default {
  lib: [
    {
      syntax: ['node >= 20.19.0'],
    },
  ],
};

If engines.node is missing or no minimum version can be inferred, Rslib continues to use 'esnext'.

An explicit lib.syntax value takes precedence over automatic inference, so existing configurations are unaffected and you can set it explicitly to override the target inferred from engines.node.

In addition, Rslib v1 adjusts the Browserslist baselines for es2023 and es2024, and adds the new es2025 target:

These options only control JavaScript and CSS syntax transformations. They do not inject polyfills for runtime APIs missing from the target environment. The practical impact of the new baselines on JavaScript transformations is limited. The main difference is that Lightning CSS may emit more modern CSS.

No changes are needed if the new baselines are suitable. To preserve the syntax target behavior from Rslib v0.x:

• If the project previously used es2023 and needs to retain the more conservative compatibility range:

  rslib.config.ts

  export default {
    lib: [
      {
  -      syntax: 'es2023',
  +      syntax: 'es2022',
      },
    ],
  };

• If the project previously used es2024 and needs to continue using a dynamic Browserslist target:

  rslib.config.ts

  export default {
    lib: [
      {
  -      syntax: 'es2024',
  +      syntax: 'esnext',
      },
    ],
  };

#Default externalsType update

For format: 'esm' output, Rslib v1 changes Rspack's default externalsType: 'module-import' to externalsType: 'modern-module':

This change only affects external CommonJS modules loaded with require() when externalsType is not explicitly configured. This includes dependencies externalized through lib.autoExternal, output.autoExternal, or output.externals, as well as Node.js built-ins externalized automatically for target: 'node'. Externals loaded with ESM imports retain their previous behavior and generally require no changes.

Note that if the output contains an external loaded through createRequire() and is bundled again, the consuming bundler must be able to statically analyze this call. Rsbuild / Rspack projects can enable module.parser.javascript.createRequire. If the change in module-loading semantics is acceptable, you can also consider migrating CommonJS require() calls in the source to ESM imports.

If only one dependency needs to retain the Rslib v0.x behavior, and its loading semantics are compatible with ESM imports, use the ${externalsType} ${libraryName} syntax in output.externals to use module-import for that dependency:

export default {
  lib: [
    {
      output: {
        externals: {
          'some-package': 'module-import some-package',
        },
      },
    },
  ],
};

To preserve the Rslib v0.x behavior for all dependencies, set externalsType to module-import through tools.rspack:

export default {
  lib: [
    {
      tools: {
        rspack(config) {
          config.externalsType = 'module-import';
        },
      },
    },
  ],
};

#@typescript/native-preview support update

In Rslib v0.x, enabling dts.tsgo caused Rslib to load @typescript/native-preview automatically to generate declaration files.

Rslib v1 does not load @typescript/native-preview by default. Instead, it resolves typescript from the project root and selects the declaration generation method based on the resolved version. When TypeScript 7+ is detected, Rslib automatically enables dts.tsgo.

To continue using @typescript/native-preview, explicitly specify its module entry through dts.typescriptPath:

import { fileURLToPath } from 'node:url';

export default {
  lib: [
    {
      dts: {
        typescriptPath: fileURLToPath(
          import.meta.resolve('@typescript/native-preview'),
        ),
      },
    },
  ],
};

#Configuration

#Enable redirect.dts.extension by default

Rslib v1 enables redirect.dts.extension by default. When bundleless declaration files are generated, import paths automatically gain or replace their extensions with JavaScript file extensions that resolve to the corresponding declaration files.

For example, when an import path corresponds to foo.d.ts, the generated output changes as follows:

-export type { Foo } from './foo';
+export type { Foo } from './foo.js';

If your consuming tools depend on type imports without extensions, or another tool handles extension rewriting, restore the Rslib 0.x behavior:

export default {
  lib: [
    {
      redirect: {
        dts: {
          extension: false,
        },
      },
    },
  ],
};

If you also configure compilerOptions.paths or dts.alias, check whether the mapped type import paths need to point directly to a concrete declaration entry. See redirect.dts.extension for details.

#Migrate lib.autoExternal

lib.autoExternal is deprecated in Rslib v1, but has not yet been removed and can still be used.

We recommend replacing it with Rsbuild's output.autoExternal option:

 export default {
   lib: [
     {
-      autoExternal: false,
+      output: {
+        autoExternal: false,
+      },
     },
   ],
 };

#Remove experiments.advancedEsm

The experiments.advancedEsm option has been removed.

This option was originally used to generate ESM output that was more suitable for static analysis and supported code splitting. In Rslib v1, this behavior is enabled by default for ESM output, so the option is no longer needed.

 export default {
   lib: [
     {
-      experiments: {
-        advancedEsm: true,
-      },
     },
   ],
 };

#JavaScript API

• The type of lib in RslibConfig has changed from LibConfig[] to LibConfig[] | undefined. Omitting lib is equivalent to configuring lib: [{}].
• The invalid 'none' value has been removed from the mode option of rslib.inspectConfig(). When mode is omitted, it is now inferred from process.env.NODE_ENV: it is 'development' when NODE_ENV is 'development', and 'production' otherwise. When mode is 'development', rslib.inspectConfig() now only outputs configurations for libraries with format: 'mf'.