{"id":17488,"library":"altair-koa-middleware","title":"Altair Koa Middleware","description":"The `altair-koa-middleware` package provides a Koa-specific integration for the Altair GraphQL Client, an open-source GraphQL IDE. It enables developers to easily serve the Altair UI from their Koa applications, simplifying the process of embedding a robust GraphQL testing interface directly into Node.js services using the Koa framework. The package is currently at version 8.5.2 and demonstrates an active release cadence with frequent updates, including minor and patch releases, indicating ongoing development and maintenance. Key differentiators for Altair, compared to alternatives like GraphiQL or GraphQL Playground, include its comprehensive feature set for development and testing GraphQL APIs, offering query history, environment management, pre-request scripts, and a more extensive user interface for API exploration and debugging.","status":"active","version":"8.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/altair-graphql/altair","tags":["javascript","altair","graphql","koa","middleware","typescript"],"install":[{"cmd":"npm install altair-koa-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add altair-koa-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add altair-koa-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for defining routes to serve the Altair GraphQL client UI within a Koa application.","package":"@koa/router","optional":false}],"imports":[{"note":"The package primarily uses named exports. While CommonJS might technically work in some setups, modern Koa applications (especially with Node.js >=12) should use ESM imports for consistency and tree-shaking benefits. The `require` syntax is generally incorrect for modern Koa middleware packages.","wrong":"const altairKoaMiddleware = require('altair-koa-middleware');","symbol":"altairKoaMiddleware","correct":"import { altairKoaMiddleware } from 'altair-koa-middleware';"},{"note":"When importing types in TypeScript, always use `import type` to ensure they are not bundled into the compiled JavaScript, which can prevent unexpected runtime errors and improve build performance.","wrong":"import { AltairKoaMiddlewareOptions } from 'altair-koa-middleware';","symbol":"AltairKoaMiddlewareOptions","correct":"import type { AltairKoaMiddlewareOptions } from 'altair-koa-middleware';"}],"quickstart":{"code":"import Koa from 'koa';\nimport Router from '@koa/router';\nimport { altairKoaMiddleware } from 'altair-koa-middleware';\n\nconst app = new Koa();\nconst router = new Router();\n\n// A simple GraphQL endpoint for Altair to connect to\nrouter.all('/graphql', (ctx) => {\n  ctx.body = {\n    data: {\n      hello: 'world',\n    },\n  };\n});\n\n// Serve the Altair GraphQL Client UI at /altair\nrouter.get('/altair', altairKoaMiddleware({\n  endpointURL: '/graphql', // The URL of your GraphQL server\n  // Example of passing additional options to Altair\n  initialQuery: `query {\n    hello\n  }`,\n  theme: 'dark',\n  // Note: For versions >= 8.5.0, these options are validated using Zod.\n  // Ensure they conform to the expected schema to avoid runtime errors.\n  // Example of headers, ensure structure matches schema:\n  // headers: {\n  //   'X-API-Key': process.env.GRAPHQL_API_KEY ?? '',\n  // },\n}));\n\napp.use(router.routes()).use(router.allowedMethods());\n\nconst PORT = 3000;\napp.listen(PORT, () => {\n  console.log(`Koa server running on http://localhost:${PORT}`);\n  console.log(`GraphQL endpoint: http://localhost:${PORT}/graphql`);\n  console.log(`Altair GraphQL Client UI: http://localhost:${PORT}/altair`);\n});\n","lang":"typescript","description":"This quickstart demonstrates how to set up a basic Koa server that exposes a GraphQL endpoint and serves the Altair GraphQL Client UI using `altair-koa-middleware`."},"warnings":[{"fix":"Review the Altair GraphQL Client documentation for the exact schema of `initOptions` and `settings`. Adjust your middleware configuration to ensure all passed options comply with the Zod validation schema. If you encounter validation errors, check the specific field causing the issue and correct its type or structure.","message":"Version 8.5.0 introduced strict validation for AltairGraphQL init options and settings using Zod. Any options passed to `altairKoaMiddleware` that do not conform to the new schema will now cause runtime errors.","severity":"breaking","affected_versions":">=8.5.0"},{"fix":"Consult the Altair GraphQL Client plugin documentation for the updated plugin schema. Ensure any custom plugin definitions or configuration objects are compliant with the new validation rules. Test plugins thoroughly after upgrading.","message":"Version 8.5.0 also added plugin schema validation. Custom plugins or plugin configurations might break if they do not adhere to the newly enforced schema.","severity":"breaking","affected_versions":">=8.5.0"},{"fix":"Upgrade to version 8.4.2 or higher immediately to mitigate the prototype pollution vulnerability. Ensure your dependencies are regularly updated to receive critical security patches.","message":"A prototype pollution vulnerability (CVE-2023-XXXX) was fixed in version 8.4.2 related to the `setByDotNotation` utility. While not directly affecting the middleware's public API, older versions could be susceptible if used in conjunction with untrusted input.","severity":"gotcha","affected_versions":"<8.4.2"},{"fix":"Always provide the `endpointURL` option to `altairKoaMiddleware` and ensure it points to the correct path of your GraphQL server. For example: `endpointURL: '/graphql'`.","message":"The `endpointURL` option is crucial for Altair to function correctly. If it's missing or incorrect, Altair will not know where to send GraphQL queries, resulting in a non-functional client UI.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Inspect the ZodError message to identify the specific `propertyName` and the expected schema. Modify the `altairKoaMiddleware` options to match the validated structure and types. Refer to Altair GraphQL Client documentation for correct option usage.","cause":"Occurs after upgrading to v8.5.0 when `altairKoaMiddleware` is configured with options that do not conform to the new Zod validation schema.","error":"ZodError: Invalid input at path 'propertyName'"},{"fix":"Ensure you are using `import { altairKoaMiddleware } from 'altair-koa-middleware';` for modern Node.js environments and check your `tsconfig.json` (if TypeScript) and `package.json` `type` field (if Node.js) to confirm module resolution settings are correct (e.g., `\"type\": \"module\"`).","cause":"This typically happens when trying to `require` the package in a module environment that expects ESM, or when there's a mismatch in named vs. default imports.","error":"TypeError: altairKoaMiddleware is not a function or is undefined"},{"fix":"Provide a valid string value for `endpointURL` in the options object passed to `altairKoaMiddleware`, pointing to your GraphQL server. Example: `altairKoaMiddleware({ endpointURL: '/graphql' })`.","cause":"The `endpointURL` option was omitted or explicitly set to an empty/null value in the `altairKoaMiddleware` configuration.","error":"Error: \"endpointURL\" is required for Altair GraphQL Client to function properly."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}