Skip to main content
Version: 4.0.0

3.x Upgrade Guide

This article will introduce how to upgrade from midway v3 to midway v4.

Upgrading from Midway v3 to Midway v4 will have some Breaking Changes. This document only lists these Breaking changes to let users know the changes in advance and make responses.

Node.js Changes

midway v4 supports from node v20 onwards, it's best to use the LTS version.

Package Version Updates

All component packages and core packages will be upgraded to 4.x versions.

Currently in beta stage

{
"dependencies": {
- "@midwayjs/bootstrap": "^3.0.0",
- "@midwayjs/core": "^3.0.0",
- "@midwayjs/koa": "^3.0.0",
- "@midwayjs/logger": "^3.0.0",
+ "@midwayjs/bootstrap": "^4.0.0-beta.1",
+ "@midwayjs/core": "^4.0.0-beta.1",
+ "@midwayjs/koa": "^4.0.0-beta.1",
+ "@midwayjs/logger": "^4.0.0",
},
"devDependencies": {
- "@midwayjs/mock": "^3.0.0",
+ "@midwayjs/mock": "^4.0.0-beta.1",
// ...
}
}

The version of @midwyajs/luckeye is excluded.

Remove @midwayjs/decorator

Starting from v4, the @midwayjs/decorator package has been removed, users can directly use @midwayjs/core instead.

- import { Controller } from '@midwayjs/decorator';
+ import { Controller } from '@midwayjs/core';

Entry Auto-scanning Capability

Starting from v4, the framework removes the implicit auto-scanning capability, users need to explicitly declare the directories that need to be scanned.

import { Configuration, CommonJSFileDetector } from '@midwayjs/core';

@Configuration({
detector: new CommonJSFileDetector(),
// ...
})
export class MainContainer {
// ...
}

You can also specify directories to ignore.

import { Configuration, CommonJSFileDetector } from '@midwayjs/core';

@Configuration({
detector: new CommonJSFileDetector({
ignore: [
'**/logs/**',
],
}),
// ...
})
export class MainContainer {
// ...
}

Duplicate check configuration is also moved to parameters.

import { Configuration, CommonJSFileDetector } from '@midwayjs/core';

@Configuration({
detector: new CommonJSFileDetector({
conflictCheck: true,
}),
// ...
})
export class MainContainer {
// ...
}

Main Framework Logging Configuration

Starting from v4, the main framework logging format returns to the midwayLogger configuration.

// *.config.ts
export default {
koa: {
- contextLoggerFormat: info => {
- const ctx = info.ctx;
- return `${info.timestamp} ${info.LEVEL} ${info.pid} [${ctx.userId} - ${Date.now() - ctx.startTime}ms ${ctx.method}] ${info.message}`;
- }
},
midwayLogger: {
clients: {
appLogger: {
+ contextFormat: info => {
+ const ctx = info.ctx;
+ return `${info.timestamp} ${info.LEVEL} ${info.pid} [${ctx.userId} - ${Date.now() - ctx.startTime}ms ${ctx.method}] ${info.message}`;
+ }
}
}
},
} as MidwayConfig;

Other components like cron, mqtt, kafka, etc., if they have related configurations, are similar to the above.

Optional Change Reference

The following is a comparison table of Breaking Changes for each package, showing specific change content classified by package name.

@midwayjs/core

@App() Decorator Changes

Use @MainApp() instead of @App() with empty parameters:

- @App()
+ @MainApp()
private app;

@Config() Decorator Changes

Use @AllConfig() to replace @Config(ALL):

- @Config(ALL)
+ @AllConfig()
private allConfig;

DecoratorManager API Adjustments

API name adjustments in DecoratorManager:

import { DecoratorManager } from '@midwayjs/core';

- DecoratorManager.listPrelaodModules()
+ DecoratorManager.listPreStartModule()

- DecoratorManager.savePreloadModule('xxxx', xxx)
+ DecoratorManager.savePreStartModule('xxxx', xxx)

@Configuration Parameter Changes

Remove conflictCheck and detectorOptions from @Configuration, these configurations will be moved to detector:

@Configuration({
- conflictCheck: true,
- detectorOptions: { ... },
+ detector: new CommonJSFileDetector({
+ conflictCheck: true,
+ // ... other configurations
+ }),
// ...
})

Container API Simplification

Removed some useless parameters from container.get and container.getAsync:

// Previously had extra parameters
- container.get(identifier, args, options)
+ container.get(identifier, args)

- container.getAsync(identifier, args, options)
+ container.getAsync(identifier, args)

Pipeline Flow Control Removal

Due to low usage and impact on dependency injection container logic, the flow control Pipeline related capabilities have been removed:

- import { Pipeline } from '@midwayjs/core';
-
- @Pipeline()
- export class MyPipeline {
- // pipeline related code
- }

If similar functionality is needed, it is recommended to use middleware or interceptors instead.

Automatic DTO Conversion Removal

Removed the automatic DTO conversion function for request parameters that would cause ambiguity with validate conversion. Now automatic conversion only takes effect when the validate or validation component is enabled:

// In v3, even without enabling validate, it would automatically convert
export class UserController {
@Post()
async create(@Body() user: CreateUserDTO) {
- // v3: Automatically converts to CreateUserDTO instance
+ // v4: Need to explicitly enable validate or validation component for conversion
return user;
}
}

// In v4, explicit configuration is needed
+ import { Configuration } from '@midwayjs/core';
+ import * as validate from '@midwayjs/validate'; // or @midwayjs/validation
+
+ @Configuration({
+ imports: [validate],
+ })
+ export class MainConfiguration {}

MidwayFrameworkType Removal

- import { MidwayFrameworkType } from '@midwayjs/core';
-
- // Get framework type
- const frameworkType = app.getFrameworkType();
- if (frameworkType === MidwayFrameworkType.WEB_KOA) {
- // koa framework related logic
- }

BaseFramework Hook Method Removal

export class CustomFramework extends BaseFramework {
- async beforeContainerReady() {
- // Logic before container ready
- }
-
- async afterContainerReady() {
- // Logic after container ready
- }
}

DataSourceManager Configuration Deprecation

// Data source manager configuration
export const dataSourceConfig = {
- cacheInstance: true,
- validateConnection: true,
// Other configurations remain unchanged
};

@midwayjs/async-hooks-context-manager

Default Enable async_local_storage

Now async_local_storage is enabled by default, code is merged into the core module, users don't need to manually import:

@midwayjs/axios

axios Export Removal

Removed the deprecated axios export:

- import { axios } from '@midwayjs/axios';
+ import { HttpService } from '@midwayjs/axios';

export class UserService {
- @Inject()
- axios: axios;

+ @Inject()
+ httpService: HttpService;

async getUser() {
- return this.axios.get('/api/user');
+ return this.httpService.get('/api/user');
}
}

@midwayjs/socketio

Built-in socket.io-redis Removal

Removed the built-in socket.io-redis, if you need Redis adapter, please manually install and configure socket.io-redis.

@midwayjs/validate

No longer updated, recommend using @midwayjs/validation component.

@midwayjs/mock

createApp Method Parameter Adjustment

Removed the last parameter of createApp, createLightApp, createFunctionApp methods, now additional components can be written in options.imports:

- createApp('path', {}, ['extra-component'])
+ createApp('path', { imports: ['extra-component'] })

If you have a lot of historical tests that are inconvenient to modify, you can use the provided createLegacyApp, createLegacyLightApp, createLegacyFunctionApp.

@midwayjs/sequelize

@BaseTable Decorator Removal

- import { BaseTable } from '@midwayjs/sequelize';
-
- @BaseTable()
- export class User extends Model {}

+ import { Table } from 'sequelize-typescript';
+
+ @Table
+ export class User extends Model {}

validateConnection Configuration Removal

// Configuration file
export default {
sequelize: {
dataSource: {
default: {
database: 'test',
username: 'root',
password: '',
- validateConnection: true, // No longer validates connection by default
// Can be manually enabled if needed
+ // validateConnection: true,
}
}
}
}

@midwayjs/tags

Package Completely Removed

This package is no longer provided in v4, need to remove related imports and configurations:

- import * as tags from '@midwayjs/tags';
-
- @Configuration({
- imports: [
- // Other components
- tags,
- ],
- })
- export class MainConfiguration {}

@midwayjs/processAgent

Package Completely Removed

This package is no longer provided in v4, need to remove related imports and configurations:

- import * as processAgent from '@midwayjs/processAgent';
-
- @Configuration({
- imports: [
- // Other components
- processAgent,
- ],
- })
- export class MainConfiguration {}