{"id":17744,"library":"koa-graphql","title":"Koa GraphQL Middleware","description":"koa-graphql is a middleware designed for Koa.js applications, enabling the quick and efficient setup of a GraphQL HTTP server. It serves as a direct port of the well-established `express-graphql` package, bringing its comprehensive features for handling GraphQL queries, mutations, and subscriptions to the Koa ecosystem. The current stable version, 0.12.0, was released in November 2021. While the project doesn't have a rapid release cadence, it provides a robust and stable foundation for integrating GraphQL into Koa-based APIs. Its key differentiators include seamless integration with Koa's middleware paradigm, out-of-the-box GraphiQL IDE support (including subscription capabilities), and extensive options for custom schema execution and error formatting. It supports both `graphql` v14 and v15 as peer dependencies, ensuring compatibility with a range of GraphQL projects and is maintained by the GraphQL community.","status":"maintenance","version":"0.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/graphql-community/koa-graphql","tags":["javascript","koa","http","graphql","middleware","api","typescript"],"install":[{"cmd":"npm install koa-graphql","lang":"bash","label":"npm"},{"cmd":"yarn add koa-graphql","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-graphql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core GraphQL library for defining and executing schemas. Required peer dependency.","package":"graphql","optional":false},{"reason":"Commonly used Koa middleware to mount the graphqlHTTP handler to a specific path.","package":"koa-mount","optional":true},{"reason":"Alternative to koa-mount for routing, often used in Koa applications.","package":"@koa/router","optional":true},{"reason":"Required for GraphQL subscription support in GraphiQL when using the v0 websocket client.","package":"subscriptions-transport-ws","optional":true},{"reason":"Required for GraphQL subscription support in GraphiQL when using the v1 websocket client.","package":"graphql-ws","optional":true}],"imports":[{"note":"As of v0.12.0, `graphqlHTTP` is a named export. Previous versions used a default export.","wrong":"import graphqlHTTP from 'koa-graphql';","symbol":"graphqlHTTP","correct":"import { graphqlHTTP } from 'koa-graphql';"},{"note":"CommonJS usage also requires named destructuring since v0.12.0.","wrong":"const graphqlHTTP = require('koa-graphql');","symbol":"graphqlHTTP","correct":"const { graphqlHTTP } = require('koa-graphql');"},{"note":"While not directly from `koa-graphql`, this is a core dependency for schema definition and is frequently used alongside `koa-graphql`.","symbol":"GraphQLSchema","correct":"import { GraphQLSchema } from 'graphql';"}],"quickstart":{"code":"import Koa from 'koa';\nimport mount from 'koa-mount';\nimport { graphqlHTTP } from 'koa-graphql';\nimport { buildSchema } from 'graphql';\n\n// Define your GraphQL Schema using GraphQL Schema Language\nconst schema = buildSchema(`\n  type Query {\n    hello: String\n    echo(message: String!): String\n  }\n\n  type Mutation {\n    add(a: Int!, b: Int!): Int\n  }\n`);\n\n// Define a root resolver to handle queries and mutations\nconst rootValue = {\n  hello: () => 'Hello from koa-graphql!',\n  echo: ({ message }: { message: string }) => message,\n  add: ({ a, b }: { a: number; b: number }) => a + b,\n};\n\nconst app = new Koa();\n\n// Mount the GraphQL middleware\napp.use(\n  mount(\n    '/graphql',\n    graphqlHTTP({\n      schema: schema,\n      rootValue: rootValue, // Provide the root resolver\n      graphiql: true, // Enable the GraphiQL IDE for easy testing\n    }),\n  ),\n);\n\nconst PORT = process.env.PORT || 4000;\napp.listen(PORT, () => {\n  console.log(`GraphQL server running on http://localhost:${PORT}/graphql`);\n  console.log(`Access GraphiQL IDE at http://localhost:${PORT}/graphql`);\n});","lang":"typescript","description":"This quickstart sets up a basic Koa server with a GraphQL endpoint using `koa-graphql`. It defines a simple schema with 'hello', 'echo', and 'add' operations, enables the GraphiQL IDE for interactive testing, and listens on port 4000."},"warnings":[{"fix":"Update imports to use named destructuring: `import { graphqlHTTP } from 'koa-graphql';` or `const { graphqlHTTP } = require('koa-graphql');`","message":"The `graphqlHTTP` function changed from a default export to a named export. Code using `import graphqlHTTP from 'koa-graphql'` or `const graphqlHTTP = require('koa-graphql')` will break.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Migrate type checking to TypeScript or use an older version of `koa-graphql` if Flowtype is critical for your project.","message":"Flowtype support was entirely removed, and the project converted all remaining files to TypeScript. This affects users relying on Flow for type checking.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Ensure `graphql` is installed with a compatible version, e.g., `npm install graphql@'^14.7.0 || ^15.3.0'`.","message":"`koa-graphql` has `graphql` as a peer dependency. Your project must explicitly install a compatible version of `graphql`.","severity":"gotcha","affected_versions":">=0.10.0"},{"fix":"Wrap the `graphqlHTTP` middleware with `convert.back()`: `app.use(mount('/graphql', convert.back(graphqlHTTP(...))));`","message":"For Koa 1 applications, `koa-graphql` middleware needs to be converted using `koa-convert` due to API changes between Koa 1 and Koa 2+.","severity":"gotcha","affected_versions":"<0.7.0 (Koa 1.x)"},{"fix":"Follow the 'Setup with Subscription Support' example in the documentation to correctly initialize the WebSocket server and pass the `subscriptionEndpoint` to GraphiQL options.","message":"Enabling GraphQL subscriptions in GraphiQL requires additional setup, including creating an `http` server and a `SubscriptionServer` instance with `subscriptions-transport-ws` or `graphql-ws`.","severity":"gotcha","affected_versions":">=0.12.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Change your import statement to use named destructuring: `import { graphqlHTTP } from 'koa-graphql';` for ESM or `const { graphqlHTTP } = require('koa-graphql');` for CommonJS.","cause":"Attempting to use `graphqlHTTP` as a default import/require after version 0.12.0, where it became a named export.","error":"TypeError: (0 , koa_graphql_1.default) is not a function"},{"fix":"Install the `graphql` package: `npm install graphql` (or `yarn add graphql`). Ensure the installed version is compatible with `koa-graphql` (e.g., `^14.7.0 || ^15.3.0`).","cause":"The `graphql` package is a peer dependency and must be installed explicitly in your project.","error":"Error: Cannot find module 'graphql' from '.../node_modules/koa-graphql'"},{"fix":"Install `koa-convert` and wrap the `graphqlHTTP` middleware: `app.use(mount('/graphql', convert.back(graphqlHTTP(...))));`","cause":"This error can occur when using `koa-graphql` with Koa 1.x without converting the middleware, as Koa 1.x uses generator functions while Koa 2.x+ uses async/await.","error":"TypeError: app.use is not a function or app.use is not a GeneratorFunction"},{"fix":"Ensure you have the correct subscription client installed (`subscriptions-transport-ws` or `graphql-ws`), an `http` server listening, and a `SubscriptionServer` instance configured as shown in the package's documentation for subscription support.","cause":"The GraphiQL interface is configured for subscriptions, but the necessary WebSocket server or client (e.g., `subscriptions-transport-ws` or `graphql-ws`) is not correctly set up or initialized.","error":"GraphiQL: Subscription client not found or not initialized. Check console for error messages."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}