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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
graphqlHTTP
✓ import { graphqlHTTP } from 'koa-graphql';
✗ import graphqlHTTP from 'koa-graphql';
As of v0.12.0, `graphqlHTTP` is a named export. Previous versions used a default export.
graphqlHTTP
✓ const { graphqlHTTP } = require('koa-graphql');
✗ const graphqlHTTP = require('koa-graphql');
CommonJS usage also requires named destructuring since v0.12.0.
GraphQLSchema
✓ import { GraphQLSchema } from 'graphql';
While not directly from `koa-graphql`, this is a core dependency for schema definition and is frequently used alongside `koa-graphql`.
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.
import Koa from 'koa';
import mount from 'koa-mount';
import { graphqlHTTP } from 'koa-graphql';
import { buildSchema } from 'graphql';
// Define your GraphQL Schema using GraphQL Schema Language
const schema = buildSchema(`
type Query {
hello: String
echo(message: String!): String
}
type Mutation {
add(a: Int!, b: Int!): Int
}
`);
// Define a root resolver to handle queries and mutations
const rootValue = {
hello: () => 'Hello from koa-graphql!',
echo: ({ message }: { message: string }) => message,
add: ({ a, b }: { a: number; b: number }) => a + b,
};
const app = new Koa();
// Mount the GraphQL middleware
app.use(
mount(
'/graphql',
graphqlHTTP({
schema: schema,
rootValue: rootValue, // Provide the root resolver
graphiql: true, // Enable the GraphiQL IDE for easy testing
}),
),
);
const PORT = process.env.PORT || 4000;
app.listen(PORT, () => {
console.log(`GraphQL server running on http://localhost:${PORT}/graphql`);
console.log(`Access GraphiQL IDE at http://localhost:${PORT}/graphql`);
});
Debug
Known issues
breakingThe `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.fixUpdate imports to use named destructuring: `import { graphqlHTTP } from 'koa-graphql';` or `const { graphqlHTTP } = require('koa-graphql');` affects: >=0.12.0
breakingFlowtype support was entirely removed, and the project converted all remaining files to TypeScript. This affects users relying on Flow for type checking.fixMigrate type checking to TypeScript or use an older version of `koa-graphql` if Flowtype is critical for your project.
affects: >=0.12.0
gotcha`koa-graphql` has `graphql` as a peer dependency. Your project must explicitly install a compatible version of `graphql`.fixEnsure `graphql` is installed with a compatible version, e.g., `npm install graphql@'^14.7.0 || ^15.3.0'`.
affects: >=0.10.0
gotchaFor Koa 1 applications, `koa-graphql` middleware needs to be converted using `koa-convert` due to API changes between Koa 1 and Koa 2+.fixWrap the `graphqlHTTP` middleware with `convert.back()`: `app.use(mount('/graphql', convert.back(graphqlHTTP(...))));` affects: <0.7.0 (Koa 1.x)
gotchaEnabling GraphQL subscriptions in GraphiQL requires additional setup, including creating an `http` server and a `SubscriptionServer` instance with `subscriptions-transport-ws` or `graphql-ws`.fixFollow the 'Setup with Subscription Support' example in the documentation to correctly initialize the WebSocket server and pass the `subscriptionEndpoint` to GraphiQL options.
affects: >=0.12.0
Errors
Common errors & fixes
TypeError: (0 , koa_graphql_1.default) is not a function
Attempting to use `graphqlHTTP` as a default import/require after version 0.12.0, where it became a named export.
fixChange your import statement to use named destructuring: `import { graphqlHTTP } from 'koa-graphql';` for ESM or `const { graphqlHTTP } = require('koa-graphql');` for CommonJS. Error: Cannot find module 'graphql' from '.../node_modules/koa-graphql'
The `graphql` package is a peer dependency and must be installed explicitly in your project.
fixInstall 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`).
TypeError: app.use is not a function or app.use is not a GeneratorFunction
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.
fixInstall `koa-convert` and wrap the `graphqlHTTP` middleware: `app.use(mount('/graphql', convert.back(graphqlHTTP(...))));` GraphiQL: Subscription client not found or not initialized. Check console for error messages.
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.
fixEnsure 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.
Audit
Dependencies
graphqlrequiredCore GraphQL library for defining and executing schemas. Required peer dependency.
koa-mountoptionalCommonly used Koa middleware to mount the graphqlHTTP handler to a specific path.
@koa/routeroptionalAlternative to koa-mount for routing, often used in Koa applications.
subscriptions-transport-wsoptionalRequired for GraphQL subscription support in GraphiQL when using the v0 websocket client.
graphql-wsoptionalRequired for GraphQL subscription support in GraphiQL when using the v1 websocket client.