{"id":21043361,"url":"https://github.com/crystallizeapi/koa-middleware-apollo","last_synced_at":"2025-05-15T17:31:37.088Z","repository":{"id":34240846,"uuid":"172471850","full_name":"CrystallizeAPI/koa-middleware-apollo","owner":"CrystallizeAPI","description":"Apollo server implementation that uses the traditional koa middleware pattern","archived":false,"fork":false,"pushed_at":"2022-02-11T16:26:21.000Z","size":292,"stargazers_count":6,"open_issues_count":9,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-19T16:43:15.783Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CrystallizeAPI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-25T09:09:08.000Z","updated_at":"2023-06-25T10:23:57.000Z","dependencies_parsed_at":"2022-07-24T18:17:10.497Z","dependency_job_id":null,"html_url":"https://github.com/CrystallizeAPI/koa-middleware-apollo","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrystallizeAPI%2Fkoa-middleware-apollo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrystallizeAPI%2Fkoa-middleware-apollo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrystallizeAPI%2Fkoa-middleware-apollo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrystallizeAPI%2Fkoa-middleware-apollo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CrystallizeAPI","download_url":"https://codeload.github.com/CrystallizeAPI/koa-middleware-apollo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254388121,"owners_count":22062988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T14:12:34.987Z","updated_at":"2025-05-15T17:31:36.407Z","avatar_url":"https://github.com/CrystallizeAPI.png","language":"JavaScript","readme":"# koa-middleware-apollo\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n\nApollo server implementation that uses the traditional koa middleware pattern. Heavily inspired by [apollo-server-koa](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-koa).\n\n_This package is a work in progress and currently does not support file uploads or GraphQL subscriptions._\n\n## Motivation\nWhile the official implementation of the Apollo GraphQL server for koa, the [apollo-server-koa](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-koa) package mentioned above, provides an easy way to get a GraphQL server up and running, it does not work the same way that other koa middleware does. Rather than adding a middleware function to the koa stack (via `app.use()`), `apollo-server-koa` exposes an `applyMiddleware` function on an instance of the `ApolloServer` class (see package documentation for further details). This can be problematic if you, for instance, want to use path parameters for your GraphQL endpoint (e.g. `/graph/:clientId`).\n\n`@crystallize/koa-middleware-apollo` exports middleware functions that integrate seamlessly into any koa middleware stack, thus providing better interoperability and allowing for greater customizability.   \n\n### Batteries not Included\nSince our aim is to integrate as seamlessly as possible into any middleware stack, we make as few assumptions as reasonably possible. Therefore, `@crystallize/koa-middleware-apollo` does not include a bodyparser, a router or anything other than the basic tools to run a GraphQL server. Contrary to `apollo-server-koa`, it also does not export [graphql-tools](https://github.com/apollographql/graphql-tools) or [apollo-server-core](https://www.npmjs.com/package/apollo-server-core), which means you will have to add that to your dependencies manually if you intend to use functionality provided by these packages (e.g. `makeExecutableSchema` or `gql` respectively).  \n\n## Installation\n```\nyarn add @crystallize/koa-middleware-apollo\n```\n\n## Basic GraphQL Server\n### `basicGraphqlServer(options[, dependencies]) -\u003e Function`\nReturns middleware for a basic GraphQL server (implemented using `ApolloServerBase` from the [apollo-server-core](https://www.npmjs.com/package/apollo-server-core) package).\n\n* `options`: Configuration object that will be passed to the `ApolloServerBase` constructor\n* `dependencies` (optional): Allows for deeper customization of middleware behavior using dependency injection for various functions (default implementations shown here):\n  * `getMethod`: `ctx =\u003e ctx.request.method`\n  * `getQuery`: `ctx =\u003e ctx.request.body`\n  * `runQuery`: `runHttpQuery` (from `apollo-server-core`)\n  * `getOptions`: `ctx =\u003e apollo.graphQLServerOptions({ ctx })` (from `apollo-server-core`)\n  * `getRequest`: `ctx =\u003e convertNodeHttpToRequest(ctx.req)`\n\n#### Example\n```js\nconst { basicGraphqlServer } = require('@crystallize/koa-middleware-apollo')\n\nconst app = require('./app')\nconst schema = require('./schema')\n\nconst middleware = basicGraphqlServer({\n  schema,\n  debug: true,\n  context: ({ ctx }) =\u003e {\n   const { user } = ctx.state\n\n   return { user }\n  }\n})\n\napp.use(middleware)\n```\n\n### `graphqlServer(apollo[, dependencies]) -\u003e Function`\nReturns middleware for a custom GraphQL server instance.\n\n* `apollo`: Instance of an `ApolloServer` class\n* `dependencies` (optional): See above\n\n## GraphQL Playground\n### `playground(options[, dependencies]) -\u003e Function`\nReturns middleware for rendering a [GraphQL playground](https://www.apollographql.com/docs/apollo-server/features/graphql-playground.html) via the [@apollographql/graphql-playground-html](https://www.npmjs.com/package/@apollographql/graphql-playground-html) package.\n\n* `options`: Configuration object that will be passed directly to the playground render function. See [docs](https://github.com/prisma/graphql-playground#usage) for available options\n* `dependencies` (optional):\n  * `getEndpoint`: Returns the GraphQL server endpoint. Will receive koa `ctx` as its only parameter. Defaults to `options.endpoint`.\n  \n# Full Example\nThis is a close to real life example implementation of a basic GraphQL server at an endpoint that makes use of a path parameter.\n\n ```js\nconst Koa = require('koa')\nconst Router = require('koa-router')\nconst bodyParser = require('koa-bodyparser')\nconst {\n  basicGraphqlServer,\n  playground\n} = require('@crystallize/koa-middleware-apollo')\n\nconst schema = require('./schema')\n\nconst router = new Router()\n\nrouter.post(\n  '/graph/:clientId',\n  basicGraphqlServer({\n    schema,\n    context: ({ ctx }) =\u003e {\n      const { clientId } = ctx.params\n\n      return { clientId }\n    }\n  })\n)\n\nrouter.get(\n  '/graph/:clientId',\n  playground(\n    {\n      settings: {\n        'editor.theme': 'light'\n      }\n    },\n    {\n      getEndpoint: ctx =\u003e `/graph/${ctx.params.clientId}`\n    }\n  )\n)\n\nconst app = new Koa()\n\napp\n  .use(bodyParser())\n  .use(router.routes())\n\napp.listen(process.env.PORT || 3000)\n\n```\n\n# Author\n[Michael Smesnik](https://github.com/daerion) at [crystallize](https://crystallize.com)\n\n# License\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrystallizeapi%2Fkoa-middleware-apollo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrystallizeapi%2Fkoa-middleware-apollo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrystallizeapi%2Fkoa-middleware-apollo/lists"}