Registry / web-framework / moleculer-apollo-server

moleculer-apollo-server

JSON →
library0.4.1jsnpmunverified

moleculer-apollo-server provides an Apollo GraphQL server as a mixin for the Moleculer API Gateway, enabling easy integration of GraphQL endpoints within a Moleculer microservices architecture. It allows developers to define GraphQL queries and mutations directly within Moleculer service actions, automatically generating a unified GraphQL schema. The current stable version is 0.4.1, released recently with updates to Moleculer 0.15.0 and Apollo Server 5. This package differentiates itself by tightly coupling GraphQL schema definition with Moleculer actions, streamlining the process of exposing microservice capabilities via GraphQL. It also offers advanced features like inter-service resolvers and subscription support. The release cadence appears to be moderate, with significant breaking changes typically occurring with major Apollo Server version upgrades, as seen in the recent v0.4.0 release.

npm install moleculer-apollo-server
INSTALL
IMPORT
SIG · MOLECULER-APOLLO-S
M
moleculer-apollo-server
web-frameworkjavascriptv0.4.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ApolloService
import { ApolloService } from 'moleculer-apollo-server';
const { ApolloService } = require('moleculer-apollo-server');
While CommonJS `require` might work in some Moleculer setups, ES module `import` is the recommended and modern approach, especially with recent Node.js versions and TypeScript configurations. The package also ships TypeScript types for better development experience.
GraphQLContext
import { GraphQLContext } from 'moleculer-apollo-server';
Type import for the GraphQL context, improved in v0.4.1 for better type safety when interacting with the Moleculer context within resolvers.
ApolloServiceOptions
import { ApolloServiceOptions } from 'moleculer-apollo-server';
Type import for configuring the ApolloService mixin options, useful for TypeScript users to ensure correct configuration.

This example sets up a Moleculer API Gateway with `moleculer-apollo-server` to expose GraphQL endpoints, demonstrating basic query and mutation definitions from a Moleculer service.

import ApiGateway from 'moleculer-web'; import { ApolloService } from 'moleculer-apollo-server'; // Basic Greeter service to expose actions via GraphQL const GreeterService = { name: 'greeter', actions: { hello: { graphql: { query: 'hello: String' }, handler(ctx) { return 'Hello Moleculer!'; } }, welcome: { params: { name: 'string' }, graphql: { mutation: 'welcome(name: String!): String' }, handler(ctx) { return `Hello ${ctx.params.name}`; } } } }; // API Gateway service with ApolloServer mixin export default { name: 'api', mixins: [ ApiGateway, ApolloService({ typeDefs: ` # Extend global types if needed, otherwise leave empty `, resolvers: {}, routeOptions: { path: '/graphql', cors: true, mappingPolicy: 'restrict' }, serverOptions: { // Apollo Server 5 options go here // E.g., include a basic plugin plugins: [ { async serverWillStart() { console.log('Apollo Server starting up...'); } } ] } }) ], // Define settings for the API Gateway itself if necessary settings: { port: process.env.PORT ?? 3000, host: process.env.HOST ?? '0.0.0.0' }, // Add the greeter service to the broker in a real app or import it created() { this.broker.createService(GreeterService); } };
Debug
Known issues
breakingVersion 0.4.0 significantly upgraded Apollo Server from v2 to v5, necessitating corresponding changes in `typeDefs`, `resolvers`, and `serverOptions`. Users migrating from older versions must review Apollo Server's migration guides for v3, v4, and v5.
fix
Consult Apollo Server's official migration documentation (e.g., v2 to v3, v3 to v4, v4 to v5) and update your `ApolloService` configuration, including `typeDefs`, `resolvers`, and `serverOptions`, to align with Apollo Server 5 API.
affects: >=0.4.0
breakingBeginning with v0.4.0, Node.js version >= 20.x.x is required. Older Node.js runtimes are no longer supported due to dependencies on features available in Node.js 20.
fix
Upgrade your Node.js environment to version 20.x.x or higher. Verify other project dependencies for compatibility with Node.js 20.
affects: >=0.4.0
breakingGraphQL file upload support was removed in v0.4.0, as Apollo Server v3+ no longer provides built-in support for it. If your application relies on file uploads, you will need to implement a separate solution.
fix
Refactor your application to handle GraphQL file uploads through an alternative mechanism. This typically involves using a separate REST endpoint or a dedicated file upload service, then referencing the uploaded files in GraphQL mutations.
affects: >=0.4.0
breakingThe built-in healthcheck endpoint was removed in v0.4.0, mirroring changes in Apollo Server v4+. Applications depending on this endpoint for liveness/readiness probes will need an alternative.
fix
Implement a custom healthcheck endpoint within your Moleculer API Gateway using a standard `moleculer-web` route, or rely on Kubernetes/Docker healthcheck mechanisms that don't depend on the Apollo Server's internal endpoint.
affects: >=0.4.0
gotchaThe peer dependency for `moleculer` was updated to `^0.14.0 || ^0.15.0` in v0.4.1. Ensure your `moleculer` version aligns with this, especially if you are using an older `moleculer` version, which might lead to unexpected behavior or runtime errors.
fix
Update your `moleculer` package to `^0.15.0` to ensure full compatibility and leverage the latest features and fixes. You may need to run `npm install moleculer@^0.15.0` or `yarn add moleculer@^0.15.0`.
affects: >=0.4.1
Errors
Common errors & fixes
Error: ApolloServer requires options to be passed to its constructor
Attempting to instantiate ApolloService without `serverOptions` or with an incorrect structure after Apollo Server 5 migration.
fix
Ensure `serverOptions` is correctly defined within the `ApolloService` mixin configuration, adhering to the Apollo Server 5 constructor options. For example, `serverOptions: { plugins: [...] }`.
TypeError: Cannot read properties of undefined (reading 'schema')
Likely a mismatch between `graphql` peer dependency versions or an issue with schema generation/loading within `moleculer-apollo-server`.
fix
Verify that `graphql` is installed and meets the `^16.0.0` peer dependency requirement. Rebuild the project if using TypeScript, and ensure `typeDefs` and `resolvers` are valid GraphQL SDL and resolver maps.
Error: You must install 'moleculer-web' package! npm i moleculer-web
`moleculer-web` is a common companion for `moleculer-apollo-server` but is not a hard dependency of the `moleculer-apollo-server` package itself, thus must be installed separately.
fix
Install the `moleculer-web` package: `npm install moleculer-web` or `yarn add moleculer-web`. Ensure it is added to your project's dependencies.
SyntaxError: Unexpected token 'export' (at ...)
Attempting to run an ES module-style project (with `import/export`) in a Node.js environment configured for CommonJS, or vice versa.
fix
Ensure your `package.json` specifies `"type": "module"` for ES Modules, or use CommonJS `require()` syntax if not. Also, verify your `tsconfig.json` `module` option is appropriate (e.g., `"module": "Node16"` or `"ESNext"`).
Upgrade
Version history
0.4.1latest on npm
Audit
Dependencies
graphqlrequiredRequired peer dependency for defining and working with GraphQL schemas and operations.
moleculerrequiredCore microservices framework peer dependency.
moleculer-webrequiredOften used alongside moleculer-apollo-server as the API Gateway for exposing the GraphQL endpoint.
Agent activity
10 hits · last 30 days
node
10
Resources