{"id":11351,"library":"moleculer-web","title":"Moleculer API Gateway","description":"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.","status":"active","version":"0.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/moleculerjs/moleculer-web","tags":["javascript","api-gateway","http-server","microservices","microservice","moleculer","typescript"],"install":[{"cmd":"npm install moleculer-web","lang":"bash","label":"npm"},{"cmd":"yarn add moleculer-web","lang":"bash","label":"yarn"},{"cmd":"pnpm add moleculer-web","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core microservices framework, moleculer-web operates as a service within it.","package":"moleculer","optional":false}],"imports":[{"note":"ApiService is typically imported as a default export, representing the service mixin itself. It is then used with `broker.createService(ApiService)`.","wrong":"import { ApiService } from 'moleculer-web';","symbol":"ApiService","correct":"import ApiService from 'moleculer-web';"},{"note":"Available as a named export since v0.10.8 for handling specific API Gateway errors. While CJS require works, ESM named import is preferred.","wrong":"const ApiGatewayErrors = require('moleculer-web').ApiGatewayErrors;","symbol":"ApiGatewayErrors","correct":"import { ApiGatewayErrors } from 'moleculer-web';"},{"note":"Provides access to built-in rate limiting store implementations, exported since v0.10.8. Use named ESM import.","wrong":"const RateLimitStores = require('moleculer-web').RateLimitStores;","symbol":"RateLimitStores","correct":"import { RateLimitStores } from 'moleculer-web';"}],"quickstart":{"code":"import { ServiceBroker } from 'moleculer';\nimport ApiService from 'moleculer-web';\n\nconst broker = new ServiceBroker({ logger: console });\n\n// Create a dummy service to expose via the API Gateway\nbroker.createService({\n    name: 'test',\n    actions: {\n        hello(): string {\n            return 'Hello API Gateway!';\n        }\n    }\n});\n\n// Load the API Gateway service\nbroker.createService(ApiService);\n\n// Start the broker and API Gateway\nbroker.start()\n    .then(() => {\n        console.log('Moleculer API Gateway started on http://localhost:3000');\n        console.log('Test URLs:');\n        console.log('- Call \"test.hello\" action: http://localhost:3000/test/hello');\n        console.log('- Get node health info: http://localhost:3000/~node/health');\n    })\n    .catch(err => {\n        console.error('Error starting Moleculer broker or API Gateway:', err);\n    });\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 22.x or later.","message":"The minimum required Node.js version has been bumped to 22.x. Ensure your environment meets this requirement before upgrading.","severity":"breaking","affected_versions":">=0.11.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.11.0-beta1"},{"fix":"Upgrade your Node.js runtime to version 20.x or later (preferably 22.x for the latest stable).","message":"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.","severity":"breaking","affected_versions":">=0.11.0-beta2 <0.11.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.11.0-beta2"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=0.10.6"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Incorrectly defined alias in route settings, often due to changes in path-to-regexp syntax or schema validation.","error":"Error: \"aliases\" definition is invalid, missing 'path' property."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'call') at ApiService.broker.call"},{"fix":"Ensure `ApiService` is only created once by the `ServiceBroker`. If using `broker.loadServices()`, check that `ApiService` is not also explicitly `createService()`'d elsewhere.","cause":"Attempting to call `broker.createService(ApiService)` multiple times, or including `ApiService` in `broker.loadServices()` when it's already created.","error":"Error: You can't start a service more than once."}],"ecosystem":"npm"}