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.

The full install guide and integration prompts unlock after purchase.