Registry / web-framework / altair-koa-middleware

altair-koa-middleware

JSON →
library8.5.2jsnpmunverified

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.

npm install altair-koa-middleware
INSTALL
IMPORT
SIG · ALTAIR-KOA-MIDDLEW
A
altair-koa-middleware
web-frameworkjavascriptv8.5.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

altairKoaMiddleware
import { altairKoaMiddleware } from 'altair-koa-middleware';
const altairKoaMiddleware = require('altair-koa-middleware');
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.
AltairKoaMiddlewareOptions
import type { AltairKoaMiddlewareOptions } from 'altair-koa-middleware';
import { AltairKoaMiddlewareOptions } from 'altair-koa-middleware';
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.

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`.

import Koa from 'koa'; import Router from '@koa/router'; import { altairKoaMiddleware } from 'altair-koa-middleware'; const app = new Koa(); const router = new Router(); // A simple GraphQL endpoint for Altair to connect to router.all('/graphql', (ctx) => { ctx.body = { data: { hello: 'world', }, }; }); // Serve the Altair GraphQL Client UI at /altair router.get('/altair', altairKoaMiddleware({ endpointURL: '/graphql', // The URL of your GraphQL server // Example of passing additional options to Altair initialQuery: `query { hello }`, theme: 'dark', // Note: For versions >= 8.5.0, these options are validated using Zod. // Ensure they conform to the expected schema to avoid runtime errors. // Example of headers, ensure structure matches schema: // headers: { // 'X-API-Key': process.env.GRAPHQL_API_KEY ?? '', // }, })); app.use(router.routes()).use(router.allowedMethods()); const PORT = 3000; app.listen(PORT, () => { console.log(`Koa server running on http://localhost:${PORT}`); console.log(`GraphQL endpoint: http://localhost:${PORT}/graphql`); console.log(`Altair GraphQL Client UI: http://localhost:${PORT}/altair`); });
Debug
Known issues
breakingVersion 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.
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.
affects: >=8.5.0
breakingVersion 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.
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.
affects: >=8.5.0
gotchaA 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.
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.
affects: <8.4.2
gotchaThe `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.
fix
Always provide the `endpointURL` option to `altairKoaMiddleware` and ensure it points to the correct path of your GraphQL server. For example: `endpointURL: '/graphql'`.
affects: >=1.0.0
Errors
Common errors & fixes
ZodError: Invalid input at path 'propertyName'
Occurs after upgrading to v8.5.0 when `altairKoaMiddleware` is configured with options that do not conform to the new Zod validation schema.
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.
TypeError: altairKoaMiddleware is not a function or is undefined
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.
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"`).
Error: "endpointURL" is required for Altair GraphQL Client to function properly.
The `endpointURL` option was omitted or explicitly set to an empty/null value in the `altairKoaMiddleware` configuration.
fix
Provide a valid string value for `endpointURL` in the options object passed to `altairKoaMiddleware`, pointing to your GraphQL server. Example: `altairKoaMiddleware({ endpointURL: '/graphql' })`.
Upgrade
Version history
8.5.2latest on npm
Audit
Dependencies
@koa/routerrequiredRequired for defining routes to serve the Altair GraphQL client UI within a Koa application.
Agent activity
41 hits · last 30 days
node
38
OpenAI (training)
1
Resources