Altair Express Middleware

Common errors

• Error: ZodError: Invalid options provided to altairExpress

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

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

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

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  Fix: Ensure your Node.js environment is updated to version 12 or higher to meet the minimum engine requirements for the package.

Install

• npm install altair-express-middleware npm
• yarn add altair-express-middleware yarn
• pnpm add altair-express-middleware pnpm

Imports

• altairExpress
  wrong:

  const altairExpress = require('altair-express-middleware');

  correct:

  import { altairExpress } from '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.

Quickstart

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