Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ApiService
✓ import ApiService from 'moleculer-web';
✗ 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
✓ import { ApiGatewayErrors } from 'moleculer-web';
✗ const ApiGatewayErrors = require('moleculer-web').ApiGatewayErrors;
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
✓ import { RateLimitStores } from 'moleculer-web';
✗ const RateLimitStores = require('moleculer-web').RateLimitStores;
Provides access to built-in rate limiting store implementations, exported since v0.10.8. Use named ESM import.
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);
});
Debug
Known issues
breakingThe minimum required Node.js version has been bumped to 22.x. Ensure your environment meets this requirement before upgrading.fixUpgrade your Node.js runtime to version 22.x or later.
affects: >=0.11.0
breakingThe 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.fixReview 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.
affects: >=0.11.0-beta1
breakingIn 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.fixUpgrade your Node.js runtime to version 20.x or later (preferably 22.x for the latest stable).
affects: >=0.11.0-beta2 <0.11.0
gotchaMany 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.fixAlways 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.
affects: >=0.11.0-beta2
gotchaThe `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`.fixEnsure `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.
affects: >=0.10.6
Errors
Common errors & fixes
Error: "aliases" definition is invalid, missing 'path' property.
Incorrectly defined alias in route settings, often due to changes in path-to-regexp syntax or schema validation.
fixReview 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
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.
fixVerify 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.
Attempting to call `broker.createService(ApiService)` multiple times, or including `ApiService` in `broker.loadServices()` when it's already created.
fixEnsure `ApiService` is only created once by the `ServiceBroker`. If using `broker.loadServices()`, check that `ApiService` is not also explicitly `createService()`'d elsewhere.
Audit
Dependencies
moleculerrequiredCore microservices framework, moleculer-web operates as a service within it.