Registry / web-framework / altair-express-middleware

altair-express-middleware

JSON →
library8.5.2jsnpmunverified

Altair Express Middleware is an active and frequently updated Express.js middleware designed to serve the Altair GraphQL Client UI. Currently at version 8.5.2, it provides a convenient way to self-host the full-featured Altair GraphQL Client within an Express application, allowing developers to interact with GraphQL APIs directly from their server. Recent releases, such as v8.5.0, introduced significant enhancements like Zod validation for initialization options and plugin schemas, and v8.2.8 brought stricter Content Security Policy (CSP) enforcement with nonces, improving security. The package aims for a regular release cadence to align with the main Altair GraphQL Client, offering features like query execution, schema introspection, and subscription support. Its key differentiator is the tight integration with the comprehensive Altair client experience, contrasting with simpler embedded GraphQL explorers.

web-frameworkhttp-networkingaws
npm install altair-express-middleware
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.

altairExpress
import { altairExpress } from 'altair-express-middleware';
const altairExpress = require('altair-express-middleware');
The primary named export for creating the middleware function. It's recommended to use ESM imports for modern Node.js applications. TypeScript users get full type inference.
AltairExpressOptions
import type { AltairExpressOptions } from 'altair-express-middleware';
Type import for configuring the middleware. Essential for TypeScript projects to ensure `altairExpress` options conform to the expected schema, especially with the introduction of Zod validation in v8.5.0.

Demonstrates setting up a basic Express server with a placeholder GraphQL endpoint and integrating the Altair GraphQL Client UI middleware, accessible at `/altair`.

import express from 'express'; import { altairExpress } from 'altair-express-middleware'; const app = express(); const PORT = process.env.PORT || 3000; // A placeholder GraphQL endpoint for Altair to connect to app.all('/graphql', (req, res) => { // In a real application, this would be your GraphQL API handler res.status(200).send('This is your GraphQL endpoint. Altair will interact with it.'); }); // Integrate Altair GraphQL Client UI app.use('/altair', altairExpress({ endpointURL: '/graphql', subscriptionsEndpoint: '/graphql', // Example of a common option: setting an initial query initialQuery: `query { __typename }`, // As of v8.5.0, these options are Zod-validated. // Ensure your options strictly adhere to AltairExpressOptions type. // Example of a newer option (introduced in v8.4.2) for allowed local storage keys // allowedLocalStorageKeys: ['myCustomKey', 'anotherKey'] })); app.listen(PORT, () => { console.log(`🚀 GraphQL API server running on http://localhost:${PORT}/graphql`); console.log(`✨ Altair GraphQL Client UI available on http://localhost:${PORT}/altair`); });
Debug
Known issues
breakingStarting from v8.5.0, Altair Express Middleware now enforces Zod validation for `altairExpress` initialization options and plugin schemas. Providing invalid or malformed options will result in runtime errors that previously might have been ignored.
fix
Review your `altairExpress` options and ensure they strictly conform to the expected types and structure. Consult the official documentation or `AltairExpressOptions` type definition for correct usage.
affects: >=8.5.0
breakingVersion 8.2.8 introduced stricter Content Security Policy (CSP) enforcement, utilizing nonces for enhanced security. Applications that embed Altair and define custom CSP headers might experience issues with scripts or styles failing to load if nonces are not correctly implemented in their CSP directives.
fix
If you use custom CSPs, ensure you retrieve and include the nonce provided by the middleware in your `script-src` and `style-src` directives. Alternatively, configure your CSP to allow Altair's embedded scripts and styles, or carefully consider disabling strict CSP if not required for your environment.
affects: >=8.2.8
gotchaThe package requires Node.js version 12 or greater. Using older Node.js versions might lead to compatibility issues or runtime errors, particularly with modern JavaScript features or dependencies.
fix
Ensure your Node.js environment is updated to version 12 or higher to meet the minimum engine requirements for the package.
affects: <=11.x
Errors
Common errors & fixes
Error: ZodError: Invalid options provided to altairExpress
The options object passed to `altairExpress` does not conform to the expected schema, which is strictly validated after v8.5.0.
fix
Carefully check the `altairExpress` configuration against the `AltairExpressOptions` type definition or the official documentation. Ensure all properties are correct, correctly typed, and conform to the new validation rules.
Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' ..."
Your application's Content Security Policy (CSP) is blocking Altair's embedded scripts or styles, primarily due to the nonce-based CSP enforcement introduced in v8.2.8.
fix
Modify your server's CSP headers to explicitly allow the nonce generated by Altair. If using `helmet` or similar middleware, you might need to configure it to allow nonces or to relax the CSP for the Altair path.
Cannot GET /altair
The Altair Express middleware has not been correctly mounted at the specified path, the server is not running, or there is a conflict with another route.
fix
Ensure `app.use('/altair', altairExpress(...))` is present in your Express application's configuration and that your server is successfully listening on the correct port. Verify that the URL path `/altair` matches where you intend to access the Altair client.
Upgrade
Version history
8.5.2latest on PyPI
Audit
Dependencies
expressrequiredRequired as the web framework to integrate the middleware.
Agent activity
100 hits · last 30 days
node
10
claudebot
4
mj12bot
3
ahrefsbot
3
Amazon
1
amazonbot
1
bytedance
1
Resources