Moleculer API Gateway

0.11.0 · active · verified Sun Apr 19

moleculer-web is the official API Gateway service for the Moleculer microservices framework. It enables publishing Moleculer services via HTTP/HTTPS, handling routing, middleware, authentication, authorization, and static file serving. Key features include multiple routing strategies (aliases, named parameters, REST shorthand), support for file uploads, CORS, ETag generation, HTTP/2, and rate limiting. It supports various body parsers (JSON, URL-encoded) and can act as a middleware in existing ExpressJS applications. The current stable version is 0.11.0, released recently. The project appears actively maintained with frequent updates, including breaking changes in major versions for Node.js compatibility and dependency updates, indicating a steady, albeit evolving, release cadence.

Common errors

```
Error: "aliases" definition is invalid, missing 'path' property.
```
cause Incorrectly defined alias in route settings, often due to changes in path-to-regexp syntax or schema validation.

fix Review your `aliases` configuration within your API Gateway routes. Ensure each alias has a correctly formatted path string and matches the updated `path-to-regexp` 8.x syntax, especially for optional parameters or complex patterns.
```
TypeError: Cannot read properties of undefined (reading 'call') at ApiService.broker.call
```
cause This error typically occurs if the API Gateway service attempts to call a Moleculer action that does not exist or is not registered, or if the broker instance is not properly initialized or accessible.

fix Verify that the target Moleculer service and action name specified in your API Gateway alias or route is correct and that the service is running and registered with the broker before the API Gateway attempts to call it.
```
Error: You can't start a service more than once.
```
cause Attempting to call `broker.createService(ApiService)` multiple times, or including `ApiService` in `broker.loadServices()` when it's already created.

fix Ensure `ApiService` is only created once by the `ServiceBroker`. If using `broker.loadServices()`, check that `ApiService` is not also explicitly `createService()`'d elsewhere.

Warnings

breaking The minimum required Node.js version has been bumped to 22.x. Ensure your environment meets this requirement before upgrading.
Fix: Upgrade your Node.js runtime to version 22.x or later.
breaking The underlying `path-to-regexp` library was updated to 8.x.x, introducing breaking changes in how path aliases are resolved. This affects how optional parameters and other path patterns are defined in your API Gateway routes.
Fix: Review the `path-to-regexp` 8.x documentation (e.g., on GitHub) for migration guidance, especially for aliases using optional parameters. Old syntax like `GET user/:name?` for optional segments will likely need adjustment.
breaking In an earlier beta, the minimum Node.js version was raised to 20.x, which was subsequently increased to 22.x in the final 0.11.0 release. If upgrading from versions prior to 0.11.0-beta2, this is the initial breaking change to be aware of.
Fix: Upgrade your Node.js runtime to version 20.x or later (preferably 22.x for the latest stable).
gotcha Many internal dependencies (major, minor, patch) are upgraded in new releases, which can contain their own breaking changes. Although not explicitly listed as `moleculer-web` breaking changes, review dependency changelogs.
Fix: Always review the full changelog and commit history for new major/minor `moleculer-web` releases, and check updated dependency documentation for potential impacts on your application.
gotcha The `qs` package, used for query string parsing, was updated to mitigate CVE-2022-24999. While addressed, ensure your dependency tree doesn't have older, vulnerable versions of `qs`.
Fix: Ensure `moleculer-web` is updated to at least `0.10.6` and run `npm audit` or `yarn audit` to check for other direct or transitive dependencies that might still rely on vulnerable `qs` versions.

Install

npm install moleculer-web npm
yarn add moleculer-web yarn
pnpm add moleculer-web pnpm

Imports

ApiService
wrong:
```
import { ApiService } from 'moleculer-web';
```
correct:
```
import ApiService from 'moleculer-web';
```
ApiService is typically imported as a default export, representing the service mixin itself. It is then used with `broker.createService(ApiService)`.
ApiGatewayErrors
wrong:
```
const ApiGatewayErrors = require('moleculer-web').ApiGatewayErrors;
```
correct:
```
import { ApiGatewayErrors } from 'moleculer-web';
```
Available as a named export since v0.10.8 for handling specific API Gateway errors. While CJS require works, ESM named import is preferred.
RateLimitStores
wrong:
```
const RateLimitStores = require('moleculer-web').RateLimitStores;
```
correct:
```
import { RateLimitStores } from 'moleculer-web';
```
Provides access to built-in rate limiting store implementations, exported since v0.10.8. Use named ESM import.

Quickstart

This quickstart demonstrates how to instantiate a Moleculer ServiceBroker and integrate the moleculer-web API Gateway to expose a simple service via HTTP, providing immediate access to actions and system endpoints.

import { ServiceBroker } from 'moleculer';
import ApiService from 'moleculer-web';

const broker = new ServiceBroker({ logger: console });

// Create a dummy service to expose via the API Gateway
broker.createService({
    name: 'test',
    actions: {
        hello(): string {
            return 'Hello API Gateway!';
        }
    }
});

// Load the API Gateway service
broker.createService(ApiService);

// Start the broker and API Gateway
broker.start()
    .then(() => {
        console.log('Moleculer API Gateway started on http://localhost:3000');
        console.log('Test URLs:');
        console.log('- Call "test.hello" action: http://localhost:3000/test/hello');
        console.log('- Get node health info: http://localhost:3000/~node/health');
    })
    .catch(err => {
        console.error('Error starting Moleculer broker or API Gateway:', err);
    });

view raw JSON →