{"id":16943,"library":"altair-express-middleware","title":"Altair Express Middleware","description":"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.","status":"active","version":"8.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/altair-graphql/altair","tags":["javascript","altair","express","graphql","middleware","typescript"],"install":[{"cmd":"npm install altair-express-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add altair-express-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add altair-express-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the web framework to integrate the middleware.","package":"express","optional":false}],"imports":[{"note":"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.","wrong":"const altairExpress = require('altair-express-middleware');","symbol":"altairExpress","correct":"import { altairExpress } from 'altair-express-middleware';"},{"note":"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.","symbol":"AltairExpressOptions","correct":"import type { AltairExpressOptions } from 'altair-express-middleware';"}],"quickstart":{"code":"import express from 'express';\nimport { altairExpress } from 'altair-express-middleware';\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\n\n// A placeholder GraphQL endpoint for Altair to connect to\napp.all('/graphql', (req, res) => {\n  // In a real application, this would be your GraphQL API handler\n  res.status(200).send('This is your GraphQL endpoint. Altair will interact with it.');\n});\n\n// Integrate Altair GraphQL Client UI\napp.use('/altair', altairExpress({\n  endpointURL: '/graphql',\n  subscriptionsEndpoint: '/graphql',\n  // Example of a common option: setting an initial query\n  initialQuery: `query {\n    __typename\n  }`,\n  // As of v8.5.0, these options are Zod-validated.\n  // Ensure your options strictly adhere to AltairExpressOptions type.\n  // Example of a newer option (introduced in v8.4.2) for allowed local storage keys\n  // allowedLocalStorageKeys: ['myCustomKey', 'anotherKey']\n}));\n\napp.listen(PORT, () => {\n  console.log(`🚀 GraphQL API server running on http://localhost:${PORT}/graphql`);\n  console.log(`✨ Altair GraphQL Client UI available on http://localhost:${PORT}/altair`);\n});","lang":"typescript","description":"Demonstrates setting up a basic Express server with a placeholder GraphQL endpoint and integrating the Altair GraphQL Client UI middleware, accessible at `/altair`."},"warnings":[{"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.","message":"Starting 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.","severity":"breaking","affected_versions":">=8.5.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=8.2.8"},{"fix":"Ensure your Node.js environment is updated to version 12 or higher to meet the minimum engine requirements for the package.","message":"The 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.","severity":"gotcha","affected_versions":"<=11.x"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The options object passed to `altairExpress` does not conform to the expected schema, which is strictly validated after v8.5.0.","error":"Error: ZodError: Invalid options provided to altairExpress"},{"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.","cause":"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.","error":"Refused to execute inline script because it violates the following Content Security Policy directive: \"script-src 'self' ...\""},{"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.","cause":"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.","error":"Cannot GET /altair"}],"ecosystem":"npm","meta_description":null}