#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": "^2.0.0",
    "@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 declaration files generation errors. This can be resolved by adding a env.d.ts file in your /src directory.

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

or

/// <reference types="@rslib/core/types" />

#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!