This document mainly introduces incompatible configuration changes and recommended migration methods when upgrading from Modern.js 2.0 to 3.0.
Change: This configuration has been removed and replaced with server.port.
Migration Example:
// Before
dev: {
port: 8080;
}
// After
server: {
port: process.env.NODE_ENV === 'development' ? 8080 : undefined;
}Change: String format is no longer supported, object format must be used.
V2 Type:
type AppIconItem = {
src: string;
size: number;
target?: 'apple-touch-icon' | 'web-app-manifest';
};
type AppIcon =
| string
| {
name?: string;
icons: AppIconItem[];
filename?: string;
};V3 Type:
type AppIconItem = {
src: string;
size: number;
target?: 'apple-touch-icon' | 'web-app-manifest';
};
type AppIcon = {
name?: string;
icons: AppIconItem[];
filename?: string;
};Migration Example:
// v2
export default {
html: {
appIcon: './src/assets/icon.png',
},
};
// v3
export default {
html: {
appIcon: {
icons: [
{
src: './src/assets/icon.png',
size: 180,
},
],
},
},
};Change: Configurations such as metaByEntries, templateParametersByEntries, injectByEntries, tagsByEnties, faviconByEntries, templateByEnties, titleByEntries have been deprecated and need to be replaced with function syntax.
Migration Steps:
html.xxx insteadMigration Example:
// v2
export default {
html: {
metaByEntries: {
foo: {
description: 'TikTok',
},
// Other configurations...
},
},
};
// v3
export default {
html: {
meta({ entryName }) {
switch (entryName) {
case 'foo':
return {
description: 'TikTok',
};
// Other configurations...
}
},
},
};Change: This configuration has been deprecated, use html.outputStructure instead.
Migration Example:
// v2 - equivalent to html.outputStructure configured as nested
export default {
html: {
disableHtmlFolder: true,
},
};
// v3
export default {
html: {
outputStructure: 'flat',
},
};Change: This configuration has been deprecated, you need to manually switch to esbuild minification.
// This configuration has been deprecated, please refer to [Switching Minifier](https://rsbuild.rs/config/output/minify#switching-minifier) to manually switch to esbuild minification
// tools: {
// esbuild: { /* configuration */ }
// },Change: This configuration has been deprecated, you need to manually switch to Terser minification.
// This configuration has been deprecated, please refer to [Switching Minifier](https://rsbuild.rs/config/output/minify#switching-minifier) to manually switch to Terser minification
// tools: {
// terser: { /* configuration */ }
// },Change 1: after, before, devMiddleware configurations have been deprecated, use dev configuration instead.
Migration Example:
// v2
export default {
tools: {
devServer: {
before: [...],
after: [...],
devMiddleware: {
writeToDisk: true
}
}
}
};
// v3
export default {
dev: {
setupMiddlewares: [...],
writeToDisk: true
}
};Change 2: client, https, liveReload configurations have been deprecated, use corresponding dev.client, dev.https, dev.liveReload configurations instead.
Migration Example:
// v2
export default {
tools: {
devServer: {
client: {
port: 8081,
},
},
},
};
// v3
export default {
dev: {
client: {
port: 8081,
},
},
};Change 3: hot configuration has been deprecated, use dev.hmr configuration instead.
Migration Example:
// v2
export default {
tools: {
devServer: {
hot: false,
},
},
};
// v3
export default {
dev: {
hmr: false,
},
};Change 4: compress, headers, historyApiFallback, watch configurations have been deprecated, use dev.server.compress, dev.server.headers, dev.server.historyApiFallback, dev.server.watch configurations instead.
Migration Example:
// v2
export default {
tools: {
devServer: {
compress: true,
headers: {
'X-Custom-Header': 'custom-value',
},
historyApiFallback: true,
watch: true,
},
},
};
// v3
export default {
dev: {
server: {
compress: true,
headers: {
'X-Custom-Header': 'custom-value',
},
historyApiFallback: true,
watch: true,
},
},
};Change: This configuration has been deprecated, use Rsbuild's Pug plugin to enable support.
Migration Example:
// v2
tools: {
pug: true,
},
// v3
import { pluginPug } from "@rsbuild/plugin-pug";
export default {
builderPlugins: [pluginPug()],
};Change: This configuration has been deprecated, please refer to the Rsdoctor documentation and use Rspack's [Rsdoctor plugin] to enable support.
Migration Example:
// v2
tools: {
rsdoctor: {
disableClientServer: true,
features: ['bundle', 'loader', 'plugins', 'resolver'],
},
},
// v3
import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
export default {
// ...
tools: {
bundlerChain(chain) {
// Only register the plugin when RSDOCTOR is true, as the plugin will increase build time
if (process.env.RSDOCTOR) {
chain.plugin('rsdoctor').use(RsdoctorRspackPlugin, [
{
// Plugin options
disableClientServer: true,
features: ['bundle', 'loader', 'plugins', 'resolver'],
},
]);
}
},
},
};Change: This configuration has been deprecated, the framework no longer includes Babel by default. Please use Rsbuild's Babel plugin to enable support.
Migration Example:
// v2
tools: {
babel: {
plugins: [
[
'babel-plugin-import',
{
libraryName: 'xxx-components',
libraryDirectory: 'es',
style: true,
},
],
],
},
}
// v3
import { pluginBabel } from '@rsbuild/plugin-babel';
export default {
// ...
builderPlugins: [
pluginBabel({
babelLoaderOptions: {
plugins: [
[
'babel-plugin-import',
{
libraryName: 'my-components',
libraryDirectory: 'es',
style: true,
},
],
],
},
})
];
}Change: This configuration has been deprecated, please refer to Tailwind Plugin Changes and use Rsbuild's approach to integrate Tailwind CSS.
Change: Since Rspack does not support tsLoader, this configuration has been deprecated. The Rspack experiments.typeReexportsPresence configuration can be used to improve recognition of TypeScript type exports, which can assist with ts-loader migration.
// This configuration has been deprecated
// tools: {
// tsLoader: { /* configuration */ }
// },Change: This configuration has been deprecated, please migrate to tools.bundlerChain.
// v2
tools: {
webpackChain: (chain, { env }) => {
if (env === 'development') {
chain.devtool('cheap-module-eval-source-map');
}
};
}
// v3
tools: {
bundlerChain: (chain, { env }) => {
if (env === 'development') {
chain.devtool('cheap-module-eval-source-map');
}
};
}Change: This configuration has been deprecated, please migrate webpack configuration to tools.rspack.
// v2
tools: {
webpack: (chain, { env }) => {
{
/* configuration */
}
};
}
// v3
tools: {
rspack: (chain, { env }) => {
{
/* configuration */
}
};
}Change: This configuration has been deprecated, use resolve.mainFields instead.
Migration Example:
// v2
source: {
resolveMainFields: ['custom', 'module', 'main'];
}
// v3
resolve: {
mainFields: ['custom', 'module', 'main'];
}Change: This configuration has been deprecated, use resolve.extensions instead.
Migration Example:
// v2
source: {
resolveExtensionPrefix: ['.ts', '.tsx', '.js'];
}
// v3
resolve: {
extensions: ['.ts', '.tsx', '.js'];
}Change: This configuration has been deprecated, remove it directly.
Change: This configuration has been deprecated, remove it directly.
Change: This configuration has been deprecated, remove it directly.
Change: This configuration no longer applies to code in custom Server and BFF. Aliases configured for server-side code need to be migrated to tsconfig.json.
Migration Example:
// v2
source: {
alias: {
'@api/*': './api/*',
},
},
// v3 tsconfig.json
{
"compilerOptions": {
"paths": {
"@api/*": ["./api/*"]
},
},
}Change: The default route has changed from main to index. If index exists in the server.routes configuration, migrate as follows.
Migration Example:
// v2
server: {
routes: {
main: '/new',
},
},
// v3
server: {
routes: {
index: '/new',
},
},Change: Needs to be handled based on the project's existing configuration.
Migration Steps:
.browserslistrc file in the projectoutput.overrideBrowserslist is configured in modern.config.[ts|js]If none of the above exist, create a .browserslistrc file with the following content for browsers supporting ES6:
chrome >= 51;
edge >= 15;
firefox >= 54;
safari >= 10;
ios_saf >= 10;Change: This configuration has been deprecated, comment it out and add a note.
// This configuration has been deprecated, if you encounter issues please contact oncall for resolution
// output: {
// enableAssetFallback: true,
// },Change: This configuration has been deprecated, use output.cssModules.localIdentName instead.
Migration Example:
// v2
export default {
output: {
cssModuleLocalIdentName: '[path][name]__[local]-[hash:base64:6]',
},
};
// v3
export default {
output: {
cssModules: {
localIdentName: '[path][name]__[local]-[hash:base64:6]',
},
},
};Change: This configuration has been deprecated, use output.injectStyles instead.
Migration Example:
// v2
export default {
output: {
disableCssExtract: true,
},
};
// v3
export default {
output: {
injectStyles: true,
},
};Change: This configuration has been deprecated, use output.filenameHash instead.
Migration Example:
// v2
export default {
output: {
disableFilenameHash: true,
},
};
// v3
export default {
output: {
filenameHash: false,
},
};Change: This configuration has been deprecated, use output.minify instead.
Migration Example:
// v2
export default {
output: {
disableMinimize: true,
},
};
// v3
export default {
output: {
minify: false,
},
};Change: This configuration has been deprecated, use output.sourceMap instead.
Migration Example:
// v2
export default {
output: {
disableSourceMap: true,
},
};
// v3
export default {
output: {
sourceMap: false,
},
};Change: This configuration has been deprecated, use output.inlineScripts instead.
Migration Example:
// v2
export default {
output: {
enableInlineScripts: true,
},
};
// v3
export default {
output: {
inlineScripts: true,
},
};Change: This configuration has been deprecated, use output.inlineStyles instead.
Migration Example:
// v2
export default {
output: {
enableInlineStyles: true,
},
};
// v3
export default {
output: {
inlineStyles: true,
},
};Change: This configuration has been deprecated, use source.decorators instead.
Migration Example:
// v2
export default {
output: {
enableLatestDecorators: true,
},
};
// v3
export default {
source: {
decorators: {
version: '2022-03',
},
},
};Change: This configuration has been deprecated, use pluginNodePolyfill plugin instead.
Migration Example:
// v2
export default {
output: {
disableNodePolyfill: false,
},
};
// v3
import { pluginNodePolyfill } from '@rsbuild/plugin-node-polyfill';
export default {
builderPlugins: [pluginNodePolyfill()],
};Change: This plugin does not require any parameters.
Migration Example:
// v2
plugins: [
appTools({
bundler: 'rspack'
})
],
// v3
plugins: [
appTools()
],Change: security.sri.hashLoading is no longer needed and can be removed directly.
Change: No longer needed, can be removed directly. This configuration has been moved to the router configuration in modern.runtime.ts.
Migration Example:
// v2
// modern.config.ts
export default {
runtime: {
router: {
// Router configuration
},
},
};
// v3
// modern.runtime.ts
import { defineRuntimeConfig } from '@modern-js/runtime';
export default defineRuntimeConfig({
router: {
// Router configuration
},
});Change: This configuration has been deprecated, it is recommended to use a third-party state management library.
Change: This configuration has been deprecated, move this configuration to the masterApp configuration in modern.runtime.ts.
Migration Example:
// v2
// modern.config.ts
export default {
runtime: {
masterApp: {
apps: [
{
name: 'Table',
entry: 'http://localhost:8081',
},
{
name: 'Dashboard',
entry: 'http://localhost:8082',
},
],
},
},
};
// v3
// modern.runtime.ts
import { defineRuntimeConfig } from '@modern-js/runtime';
export default defineRuntimeConfig({
masterApp: {
apps: [
{
name: 'Table',
entry: 'http://localhost:8081',
},
{
name: 'Dashboard',
entry: 'http://localhost:8082',
},
],
},
});Change: This configuration has been deprecated, it is recommended to use Rsdoctor to analyze bundle size.
Change: No longer needed, can be removed directly.
Migration Example:
// v2
export default {
performance: {
transformLodash: true,
},
};
// v3 - Remove this configuration directly
export default {
// Configuration...
};Change: This configuration has been deprecated, changed to dev.lazyCompilation.
Migration Example:
// v2
experiments: {
lazyCompilation: true;
}
// v3
dev: {
lazyCompilation: true;
}