Modern.js Module#

This section introduces how to migrate a project using Modern.js Module to Rslib.

Adapt package.json#

Rslib has a minimal dependency footprint. For the basic functionality you only need the package @rslib/core.

You can create a new Rslib project by following the Quick Start to see the package.json file. Then update your existing package.json file like below:

• Remove the fields main, lint-staged, simple-git-hooks, sideEffects and publishConfig
• Change the types field from ./dist/types/index.d.ts to ./dist/index.d.ts
• Change the module field from ./dist/es/index.js to ./dist/index.js
• Remove the scripts fields prepare, build:watch, reset, change, bump, pre, change-status, gen-release-note, release, new, upgrade
• Change the script build from modern build to rslib build
• Change the script dev from modern dev to rslib build --watch
• Change the script lint name to check and keep the value
• Add a new script format with the value biome format --write
• Add the script test with the value vitest run
• Add the field exports (object)
  • Add the field "." (object)
  • Add the fields "types": "./dist/index.d.ts" and "import": "./dist/index.js"
• Add the field files with the value ["dist"]
• Depending on your configuration and use-case the devDependencies can vary
  • It is important to replace @modern-js/module-tools with @rslib/core
  • We do not need rimraf, lint-staged and simple-git-hooks anymore for starters
• Copy over your required dependencies and peerDependencies if needed

Your package.json should look something like this:

{
  "name": "rslib",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "rslib build",
    "check": "biome check --write",
    "dev": "rslib build --watch",
    "format": "biome format --write",
    "test": "vitest run"
  },
  "devDependencies": {
    "@biomejs/biome": "^1.9.3",
    "@rslib/core": "^0.1.3",
    "typescript": "^5.6.3",
    "vitest": "^2.1.8"
  },
  "peerDependencies": {},
  "dependencies": {}
}

Adapt bundler config#

Now we have a clean slate to work with. We will continue with the Rslib configuration. It follows the same pattern as all Rs* projects. Since this step is very unique for every environment, below is an basic example:

Replace your modern.config.ts with a rslib.config.ts:

import { defineConfig } from '@rslib/core';

export default defineConfig({
  source: {
    entry: {
      index: ['./src/**'],
    },
  },
  lib: [
    {
      bundle: false,
      dts: true,
      format: 'esm',
    },
  ],
});

TypeScript Declaration#

If you use Typescript in your Modern.js Module and need to generate declaration files, add the following changes:

import { defineConfig } from '@rslib/core';

export default defineConfig({
  //...
  lib: [
    {
      //...
      dts: true,
    },
  ],
});

React#

If you use React in your Modern.js Module, add the following changes:

import { defineConfig } from '@rslib/core';
// Quick tip: You can use all Rsbuild plugins here since they are compatible with Rslib
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  //...
  output: {
    target: 'web',
  },
  plugins: [pluginReact()],
});

In addition, you have to install the @rsbuild/plugin-react package as devDependencies.

npm add @rsbuild/plugin-react -D

Sass#

If you use Sass in your Modern.js Module, add the following changes:

import { defineConfig } from '@rslib/core';
// Quick tip: You can use all Rsbuild plugins here since they are compatible with Rslib
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  //...
  plugins: [pluginSass()],
});

In addition, you have to install the @rsbuild/plugin-sass package as devDependencies.

npm add @rsbuild/plugin-sass -D

If you run Typescript together with Sass, you might run into DTS generation errors. This can be resolved by adding a global.d.ts file in your /src directory.

declare module '*.scss' {
  const content: { [className: string]: string };
  export default content;
}

CSS Modules#

If you use CSS Modules in your Modern.js Module, add the following changes:

import { defineConfig } from '@rslib/core';
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  lib: [
    {
      //...
      output: {
        cssModules: {
          // the CSS Modules options are 1:1 the same as in the official "css-modules" package
          localIdentName: '[local]--[hash:base64:5]',
        },
      },
    },
  ],
  plugins: [pluginSass()],
});

Contents Supplement#

This migration doc is contributed by community user YanPes. Much appreciation for his contribution!

Rslib is designed to be next generation of Modern.js Module and we will provide more detailed guide and scripts for migration in 2025 Q1.