Altair Koa Middleware

8.5.2 verified Thu Apr 23 auth: no javascript

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.

Common errors

error ZodError: Invalid input at path 'propertyName' ↓

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

error TypeError: altairKoaMiddleware is not a function or is undefined ↓

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.

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 Error: "endpointURL" is required for Altair GraphQL Client to function properly. ↓

cause 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' }).

Warnings

breaking 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. ↓

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.

breaking 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. ↓

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.

gotcha 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. ↓

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.

gotcha 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. ↓

fix Always provide the `endpointURL` option to `altairKoaMiddleware` and ensure it points to the correct path of your GraphQL server. For example: `endpointURL: '/graphql'`.

Install

npm install altair-koa-middleware

yarn add altair-koa-middleware

pnpm add altair-koa-middleware

Imports

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

Quickstart

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`);
});