@graphql-ez/plugin-altair

Integration with Altair GraphQL Client IDE

Usage

import { ezAltairIDE } from '@graphql-ez/plugin-altair';

const ezApp = CreateApp({
  ez: {
    plugins: [
      ezAltairIDE({
        // Options
      }),
      // ...
    ],
  },
  // ...
});

Options

Most of these types come from altair-static

type AltairOptions =
  | {
      /**
       * @default "/altair"
       */
      path?: string;

      /**
       * URL to be used as a base for relative URLs
       */
      baseURL?: string;
      /**
       * Whether to render the initial options in a separate javascript file or not.
       * Use this to be able to enforce strict CSP rules.
       * @default false
       */
      serveInitialOptionsInSeperateRequest?: boolean;

      /**
       * URL to set as the server endpoint
       */
      endpoint?: string;
      /**
       * URL to set as the subscription endpoint
       */
      subscriptionsEndpoint?: string;
      /**
       * Initial query to be added
       */
      initialQuery?: string;
      /**
       * Initial variables to be added
       */
      initialVariables?: string;
      /**
       * Initial pre-request script to be added
       */
      initialPreRequestScript?: string;
      /**
       * Initial post-request script to be added
       */
      initialPostRequestScript?: string;
      /**
       * Initial headers object to be added
       * @example
       * {
       *  'X-GraphQL-Token': 'asd7-237s-2bdk-nsdk4'
       * }
       */
      initialHeaders?: IDictionary;
      /**
       * Initial Environments to be added
       * @example
       * {
       *   base: {
       *     title: 'Environment',
       *     variables: {}
       *   },
       *   subEnvironments: [
       *     {
       *       title: 'sub-1',
       *       variables: {}
       *     }
       *   ]
       * }
       */
      initialEnvironments?: IInitialEnvironments;
      /**
       * Namespace for storing the data for the altair instance.
       * Use this when you have multiple altair instances running on the same domain.
       * @example
       * instanceStorageNamespace: 'altair_dev_'
       */
      instanceStorageNamespace?: string;
      /**
       * Initial app settings to use
       */
      initialSettings?: Partial<SettingsState>;
      /**
       * Initial subscriptions provider
       *
       * @default "websocket"
       */
      initialSubscriptionsProvider?: SubscriptionProviderIds;
      /**
       * Initial subscriptions connection params
       */
      initialSubscriptionsPayload?: IDictionary;
      /**
       * Indicates if the state should be preserved for subsequent app loads
       *
       * @default true
       */
      preserveState?: boolean;
      /**
       * HTTP method to use for making requests
       */
      initialHttpMethod?: HttpVerb;
    }
  | boolean;

Unpkg Version

This plugin also provides a version of Altair that is hosted by Unpkg, which is very useful when you are bundling your API, since the static files of Altair might not be included in your final bundle, but it will require an internet connection from your API.

import { ezUnpkgAltairIDE } from '@graphql-ez/plugin-altair';

const ezApp = CreateApp({
  ez: {
    plugins: [
      ezUnpkgAltairIDE({
        // Options
      }),
      // ...
    ],
  },
  // ...
});

Next.js Usage

In Next.js you need to use this plugin's handler explicitly in your API routes, for example, following the file structure: /pages/api/altair/[[...any]].ts, and using this snippet:

// /pages/api/altair/[[...any]].ts
import { UnpkgAltairHandler } from '@graphql-ez/plugin-altair/unpkg';

export default UnpkgAltairHandler({
  path: '/api/altair',
  endpointURL: '/api/graphql',
});

Vercel Usage

For Vercel you need to use this plugin's handler explicitly in your API routes in conjunction with a custom vercel.json, for example, following the file structure: /api/altair.ts, and using these snippets:

// /api/altair.ts
import { UnpkgAltairHandler } from '@graphql-ez/plugin-altair/unpkg';

export default UnpkgAltairHandler({
  path: '/api/altair',
  endpointURL: '/api/graphql',
});

/vercel.json

{
  "rewrites": [
    {
      "source": "/api/altair/(.*)",
      "destination": "/api/altair"
    }
  ]
}

Cloudflare Workers Usage

For Cloudflare Workers you can only use the Unpkg version, and make sure to import it via '@graphql-ez/plugin-altair/unpkg':

import { ezUnpkgAltairIDE } from '@graphql-ez/plugin-altair/unpkg';

const ezApp = CreateApp({
  ez: {
    plugins: [
      ezUnpkgAltairIDE({
        // Options
      }),
      // ...
    ],
  },
  // ...
});

Sveltekit Usage

Altair requires a "wildcard" route, therefore, you have to define the endpoint as Fallthrough Routes, for example /src/routes/api/[...any].ts

For example:

// /src/routes/api/[...any].ts

// import { ezAltairIDE } from '@graphql-ez/plugin-altair';
import { ezUnpkgAltairIDE } from '@graphql-ez/plugin-altair/unpkg';

const ezApp = CreateApp({
  path: '/api/graphql',
  ez: {
    plugins: [
      // ...
      ezUnpkgAltairIDE({
        path: '/api/altair',
      }),
    ],
  },
  // ...
});

const { handler } = ezApp.buildApp();

export const get = handler;

export const post = handler;