Required dependencies

npm install @midwayjs/core @midwayjs/decorator reflect-metadata
npm install @midwayjs/web-koa @midwayjs/koa
npm install @midwayjs/bootstrap
npm install @midwayjs/axios axios
npm install @midwayjs/bull bull
npm install @midwayjs/bull-board @bull-board/api
npm install @midwayjs/typeorm typeorm
npm install @midwayjs/redis ioredis
npm install @midwayjs/jwt jsonwebtoken
npm install @midwayjs/swagger
npm install @midwayjs/validate
npm install tslib typescript

TypeScript experimentalDecorators and emitDecoratorMetadata must be enabled (see setup below). No native build steps are required for core packages; some integrations (e.g., grpc) may require platform-specific native addons.

Project setup

1. Copy source - place the source/ directory at the root of your project, e.g. ./midway-packages/.

2. tsconfig.json - enable decorator metadata and set path aliases:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2019",
    "module": "commonjs",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@midwayjs/core": ["./midway-packages/core/src"],
      "@midwayjs/axios": ["./midway-packages/axios/src"],
      "@midwayjs/bootstrap": ["./midway-packages/bootstrap/src"],
      "@midwayjs/bull": ["./midway-packages/bull/src"],
      "@midwayjs/bull-board": ["./midway-packages/bull-board/src"],
      "@midwayjs/api-bridge": ["./midway-packages/api-bridge/src"]
    }
  }
}

3. Environment variables - create a .env file:

MIDWAY_SERVER_ENV=local
NODE_ENV=development

4. Entry point - import Bootstrap from the bootstrap package and call .run():

// bootstrap.js
const { Bootstrap } = require('./midway-packages/bootstrap/src');
Bootstrap.run();

5. Import reflect-metadata at the very top of your application entry before any other imports.

Public API

Bootstrap

import { Bootstrap, BootstrapStarter } from './midway-packages/bootstrap/src';
Bootstrap.run(): Promise<void>;

Bootstrap is the application entry-point launcher. Call Bootstrap.run() from your main file to initialize the IoC container, load all components, and start the configured web framework. BootstrapStarter provides lower-level control for customizing startup order.

ApiBridgeTransportAdapter

export type ApiBridgeTransportAdapter = <TInput = unknown, TOutput = unknown>(
  request: ApiBridgeTransportRequest<TInput>
) => Promise<TOutput>;

A function type used to define custom transport logic for the API bridge. Supply a concrete implementation to intercept and fulfill bridge requests, for example wrapping an axios instance or a fetch call. Used in CreateClientOptions.adapter.

CreateClientOptions

export interface CreateClientOptions extends ApiBridgeOptions {
  basePath?: ApiBridgeBasePath;
  manifest?:
    | ApiRouteManifestLike[]
    | Promise<ApiRouteManifestLike[]>
    | (() => ApiRouteManifestLike[] | Promise<ApiRouteManifestLike[]>)
    | string
    | false;
}

Configuration object passed to the API bridge client factory. basePath controls the URL root (supports static string, browser/server split, or a resolver function). manifest declares the available routes—pass a JSON path, an array, or a lazy loader.

ClusterManager

import { ClusterManager } from './midway-packages/bootstrap/src';

Manages multi-process cluster forking. Extend or instantiate ClusterManager to control worker lifecycle, restart strategies, and IPC. Use alongside AbstractForkManager for custom process topologies.

BullQueue

import { BullFramework as Framework, BullQueue } from './midway-packages/bull/src';

BullQueue is the Midway-wrapped Bull queue class. Register it via the DI container and use the exported decorators to define processors. BullFramework wires queues into the Midway application lifecycle.

Working examples

Scenario - Bootstrap a Koa application

Bootstrap a minimal Midway Koa server using the packages from source.

// src/index.ts
import 'reflect-metadata';
import { Bootstrap } from '../midway-packages/bootstrap/src';

(async () => {
  await Bootstrap.run();
})();

Scenario - Custom API bridge adapter with axios

Wire a custom transport adapter that uses an axios-like instance to forward bridge requests.

import type {
  ApiBridgeTransportAdapter,
  ApiBridgeTransportRequest,
  AxiosLikeInstance,
} from '../midway-packages/api-bridge/src';

function createAxiosAdapter(client: AxiosLikeInstance): ApiBridgeTransportAdapter {
  return async <TInput, TOutput>(
    request: ApiBridgeTransportRequest<TInput>
  ): Promise<TOutput> => {
    const response = await client.request<TOutput>({
      url: request.operation.fullPath,
      method: request.operation.method,
      data: request.input,
    });
    return response.data;
  };
}

// Usage:
// const adapter = createAxiosAdapter(myAxiosInstance);
// pass adapter into CreateClientOptions when constructing the bridge client

Scenario - Register a Bull queue processor

Define a queue and processor using the bull package decorators.

import { BullQueue } from '../midway-packages/bull/src';

// Assuming Midway decorator usage from @midwayjs/bull
@BullQueue({ name: 'email' })
export class EmailQueue {
  async process(job: { data: { to: string; subject: string } }) {
    console.log(`Sending email to ${job.data.to}: ${job.data.subject}`);
  }
}

Scenario - Mount Bull Board middleware

Expose the Bull Board dashboard in an existing Midway app.

import { BullBoardConfiguration as Configuration } from '../midway-packages/bull-board/src';
import { BullAdapter } from '@bull-board/api/bullAdapter';
import { MidwayAdapter } from '../midway-packages/bull-board/src';

// In your configuration file, import Configuration and register it
// as a Midway component. The MidwayAdapter bridges Bull Board's
// HTTP handlers to Koa or Express middleware automatically.
export { Configuration };
export { BullAdapter, MidwayAdapter };

File walkthrough

• api-bridge/ - Defines transport types (ApiBridgeTransportAdapter), operation descriptors, and CreateClientOptions for building type-safe API bridge clients between frontend and backend.
• axios/ - Re-exports the raw Axios constructor plus Midway-DI-aware Configuration, service factory, and HTTP service class for making outbound HTTP calls.
• bootstrap/ - Application launcher (Bootstrap, BootstrapStarter), cluster process manager (ClusterManager), and sticky-session master setup (setupStickyMaster).
• bull/ - Bull queue framework adapter, BullQueue class, job decorators, and interface types for background job processing.
• bull-board/ - Wires the @bull-board/api dashboard UI into Midway as middleware, exposing adapters for both Bull and BullMQ.
• bullmq/ - BullMQ-specific framework adapter parallel to the bull/ package.
• busboy/ through ws/ - Individual integration packages; each follows the same pattern: a Configuration export, a framework or service export, decorators, and interface types.

Common pitfalls and fixes

• Missing reflect-metadata import - emitDecoratorMetadata requires import 'reflect-metadata' as the very first line of your entry file; omitting it causes silent DI failures.
• experimentalDecorators not enabled - TypeScript will reject all @Decorator syntax; ensure both experimentalDecorators: true and emitDecoratorMetadata: true are in tsconfig.json.
• ESM/CJS interop with axios - The axios/src/index.ts uses axios['default'] to handle the default export; if you replace axios with a newer ESM build, this accessor will break—pin axios to ^1.x CJS build.
• Path aliases not resolved at runtime - tsconfig paths are compile-time only; add tsconfig-paths or use ts-node -r tsconfig-paths/register for dev, and a bundler alias for production.
• Bull/BullMQ peer dependency mismatch - bull-board requires @bull-board/api; install it explicitly and match the version expected by the adapter or you will get adapter registration errors at startup.
• ClusterManager in single-process dev - ClusterManager forks OS processes and should not be used in watch/dev mode; guard with if (cluster.isPrimary) or use Bootstrap directly for local development.

Vibe-coding prompt template

I have the Midway framework monorepo source in `./source/` (e.g. source/core, source/bootstrap,
source/api-bridge, source/bull, etc.) and a USAGE.md in the same directory.

The upstream package is `user@example.com`.

Please help me integrate Midway into my existing Node.js/TypeScript project step by step:

1. Read USAGE.md fully before making any changes.
2. Update tsconfig.json to enable experimentalDecorators, emitDecoratorMetadata, and add path
   aliases for every source/ package I need (at minimum: core, bootstrap, web-koa, axios).
3. Add `import 'reflect-metadata'` as the first line of my application entry.
4. Wire Bootstrap.run() in my entry point, importing from source/bootstrap/src.
5. If I need background jobs, register a BullQueue processor using source/bull/src exports.
6. If I need an API bridge, create a custom ApiBridgeTransportAdapter using the types from
   source/api-bridge/src/index.ts and show me how to pass it in CreateClientOptions.
7. Show me only real exports visible in the source files - do not invent any API surface.
8. For each step, show the full file content after your changes, not just a diff.

License and credit

Midway is licensed under the MIT License. See source/LICENSE if present, or refer to the upstream repository. Credit: Alibaba / MidwayJS team.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.