{"id":11350,"library":"moleculer-apollo-server","title":"Apollo GraphQL Server for Moleculer","description":"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.","status":"active","version":"0.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/moleculerjs/moleculer-apollo-server","tags":["javascript","graphql","apollo-server","apollo","moleculer","microservice","gateway","typescript"],"install":[{"cmd":"npm install moleculer-apollo-server","lang":"bash","label":"npm"},{"cmd":"yarn add moleculer-apollo-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add moleculer-apollo-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for defining and working with GraphQL schemas and operations.","package":"graphql","optional":false},{"reason":"Core microservices framework peer dependency.","package":"moleculer","optional":false},{"reason":"Often used alongside moleculer-apollo-server as the API Gateway for exposing the GraphQL endpoint.","package":"moleculer-web","optional":false}],"imports":[{"note":"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.","wrong":"const { ApolloService } = require('moleculer-apollo-server');","symbol":"ApolloService","correct":"import { ApolloService } from 'moleculer-apollo-server';"},{"note":"Type import for the GraphQL context, improved in v0.4.1 for better type safety when interacting with the Moleculer context within resolvers.","symbol":"GraphQLContext","correct":"import { GraphQLContext } from 'moleculer-apollo-server';"},{"note":"Type import for configuring the ApolloService mixin options, useful for TypeScript users to ensure correct configuration.","symbol":"ApolloServiceOptions","correct":"import { ApolloServiceOptions } from 'moleculer-apollo-server';"}],"quickstart":{"code":"import ApiGateway from 'moleculer-web';\nimport { ApolloService } from 'moleculer-apollo-server';\n\n// Basic Greeter service to expose actions via GraphQL\nconst GreeterService = {\n    name: 'greeter',\n    actions: {\n        hello: {\n            graphql: {\n                query: 'hello: String'\n            },\n            handler(ctx) {\n                return 'Hello Moleculer!';\n            }\n        },\n        welcome: {\n            params: {\n                name: 'string'\n            },\n            graphql: {\n                mutation: 'welcome(name: String!): String'\n            },\n            handler(ctx) {\n                return `Hello ${ctx.params.name}`;\n            }\n        }\n    }\n};\n\n// API Gateway service with ApolloServer mixin\nexport default {\n    name: 'api',\n    mixins: [\n        ApiGateway,\n        ApolloService({\n            typeDefs: `\n                # Extend global types if needed, otherwise leave empty\n            `,\n            resolvers: {},\n            routeOptions: {\n                path: '/graphql',\n                cors: true,\n                mappingPolicy: 'restrict'\n            },\n            serverOptions: {\n                // Apollo Server 5 options go here\n                // E.g., include a basic plugin\n                plugins: [\n                    {\n                        async serverWillStart() {\n                            console.log('Apollo Server starting up...');\n                        }\n                    }\n                ]\n            }\n        })\n    ],\n    // Define settings for the API Gateway itself if necessary\n    settings: {\n        port: process.env.PORT ?? 3000,\n        host: process.env.HOST ?? '0.0.0.0'\n    },\n    // Add the greeter service to the broker in a real app or import it\n    created() {\n        this.broker.createService(GreeterService);\n    }\n};\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Upgrade your Node.js environment to version 20.x.x or higher. Verify other project dependencies for compatibility with Node.js 20.","message":"Beginning 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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"GraphQL 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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.4.0"},{"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`.","message":"The 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.","severity":"gotcha","affected_versions":">=0.4.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `serverOptions` is correctly defined within the `ApolloService` mixin configuration, adhering to the Apollo Server 5 constructor options. For example, `serverOptions: { plugins: [...] }`.","cause":"Attempting to instantiate ApolloService without `serverOptions` or with an incorrect structure after Apollo Server 5 migration.","error":"Error: ApolloServer requires options to be passed to its constructor"},{"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.","cause":"Likely a mismatch between `graphql` peer dependency versions or an issue with schema generation/loading within `moleculer-apollo-server`.","error":"TypeError: Cannot read properties of undefined (reading 'schema')"},{"fix":"Install the `moleculer-web` package: `npm install moleculer-web` or `yarn add moleculer-web`. Ensure it is added to your project's dependencies.","cause":"`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.","error":"Error: You must install 'moleculer-web' package! npm i moleculer-web"},{"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\"`).","cause":"Attempting to run an ES module-style project (with `import/export`) in a Node.js environment configured for CommonJS, or vice versa.","error":"SyntaxError: Unexpected token 'export' (at ...)"}],"ecosystem":"npm"}