#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 ESM output (format: 'esm'), 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';
        },
      },
    },
  ],
};

#Default environment variable handling update

In Rslib v0.x, the following Rsbuild default environment variables are replaced with specified values at build time:

• import.meta.env.MODE
• import.meta.env.DEV
• import.meta.env.PROD
• import.meta.env.SSR
• import.meta.env.BASE_URL
• import.meta.env.ASSET_PREFIX
• process.env.BASE_URL
• process.env.ASSET_PREFIX

Rslib v1 changes how these variables are handled when format is 'esm' or 'cjs':

For complete details on how Rslib v1 handles environment variables, see Environment variables.

If your project relies on Rslib v0.x replacing these variables at build time, explicitly define the variables it uses with source.define to restore the previous behavior. To use import.meta.env.* in CJS output, you must also explicitly define the corresponding variables:

export default {
  source: {
    define: {
      'import.meta.env.MODE': JSON.stringify('production'),
      'process.env.BASE_URL': JSON.stringify('/'),
      'process.env.ASSET_PREFIX': JSON.stringify(''),
    },
  },
};

#Resource module handling updates

Rslib v1 changes how ESM output (format: 'esm') handles static assets referenced by new URL(), Web Workers, and Wasm modules.

#Static assets with new URL()

Rslib v1 treats statically analyzable new URL() references as static assets when building ESM output. Consider a source file that references logo.svg:

const logo = new URL('./assets/logo.svg', import.meta.url);

For project source, Rslib v0.x preserved the expression and did not emit logo.svg. Rslib v1 emits the file and rewrites the path in new URL() to a relative path that points to the emitted asset.

const logo = new URL('./static/svg/logo.svg', import.meta.url);

For third-party dependencies bundled into the output, Rslib v0.x rewrote the asset path in new URL() as a module reference and injected runtime code to load that module and compute the base URL. Rslib v1 handles these references in the same way as project source, emitting the referenced assets and rewriting the paths in new URL() to relative paths that point to the emitted files.

If a project previously copied these assets through output.copy or a script, and Rslib emits them from new URL() references after the upgrade, remove the corresponding configuration or script to avoid duplicate outputs. In bundleless mode (bundle: false), if source.entry also matches these assets, exclude them to avoid generating an additional JavaScript entry for the same file.

To skip Rslib's static asset processing for new URL() references, choose an approach based on the required scope. For details, see Skip new URL() processing.

• Skip one reference: Add the rspackIgnore magic comment before the first argument of new URL().

  src/index.ts

  const logo = new URL(
    /* rspackIgnore: true */ './assets/logo.svg',
    import.meta.url,
  );

• Skip all references: Use tools.bundlerChain to set the url parser option of the rslib:new-url rule to false.

  rslib.config.ts

  import { defineConfig } from '@rslib/core';
  
  export default defineConfig({
    tools: {
      bundlerChain(chain) {
        chain.module.rule('rslib:new-url').parser({
          url: false,
        });
      },
    },
  });

Additionally, Rslib's default handling requires the target of a new URL() reference to resolve to an existing source file at build time, while directories and files that exist only in the build output cannot be processed as static assets. For example:

const currentDirectory = new URL('.', import.meta.url);
const generatedFile = new URL('./generated.js', import.meta.url);

For these references, use one of the approaches above to skip new URL() processing. If these references are only used to obtain file system paths in Node.js, you can also modify the source to use Node.js path and url APIs:

import path from 'node:path';
import { fileURLToPath } from 'node:url';

const currentDirectory = path.dirname(fileURLToPath(import.meta.url));
const generatedFile = path.join(currentDirectory, 'generated.js');

For more details, see Static assets - new URL imports.

#Web Workers

When building ESM output, Rslib v1 parses new Worker(new URL(...)) and treats the referenced local script as a Worker entry. Consider a Worker defined in worker.ts:

new Worker(new URL('./worker.ts', import.meta.url));

Rslib v0.x preserved this expression and did not build worker.ts from the reference. Rslib v1 builds the Worker and its dependencies, rewrites the URL to the corresponding output path, and adds type: 'module':

new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module',
});

If the project previously configured the Worker source as a separate entry and referenced the expected .js output in the source code, remove the entry after upgrading and reference the Worker source file directly:

 export default {
   source: {
     entry: {
       index: './src/index.ts',
-      worker: './src/worker.ts',
     },
   },
 };

-new Worker(new URL('./worker.js', import.meta.url));
+new Worker(new URL('./worker.ts', import.meta.url));

For more details, see Web Workers.

#Wasm

Rslib v1 provides two output modes for Wasm modules in ESM output:

• compile mode: Rslib generates the JavaScript code required to load and instantiate Wasm modules and emits hashed .wasm files.
• preserve mode: JavaScript retains its .wasm imports, while .wasm files keep their original filenames and source-relative directory structure. These imports must be processed by a downstream bundler or target runtime that supports WebAssembly ESM Integration.

In bundleless mode, Rslib v0.x generated the JavaScript code required to load and instantiate Wasm modules. Rslib v1 uses preserve mode by default and keeps .wasm imports in JavaScript. To use compile mode instead, configure wasm.mode:

export default {
  lib: [
    {
      format: 'esm',
      bundle: false,
      wasm: {
        mode: 'compile',
      },
    },
  ],
};

Wasm handling in bundle mode remains unchanged.

For more details, see Wasm - Output modes.

#@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'),
        ),
      },
    },
  ],
};

#Node.js template update

Rslib v1 no longer provides a dual ESM/CJS Node.js template and only provides a pure ESM template. When creating a project, update the --template argument as follows:

For example, update a command that uses the previous pure ESM template as follows:

-npx create-rslib my-project --template node-esm
+npx create-rslib my-project --template node

Additionally, the new template sets engines.node to ^20.19.0 || >=22.12.0 by default and no longer configures lib.syntax explicitly. Rslib automatically infers lib.syntax from engines.node; see Default syntax target update for details.

Every Node.js version covered by engines.node supports require(ESM), so existing CommonJS consumers can now load the pure ESM package directly with require(), provided that neither the entry nor its dependencies use top-level await:

const packageExports = require('pure-esm-package');

If you still need a dual ESM/CJS template, use the following command to create one with the previous generator:

npx -y create-rslib@0.23.2 my-project --template node-dual

#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'.