Monaco GraphQL

GraphQL language plugin for the Monaco Editor. You can use it to build vscode/codespaces-like web or desktop IDEs using whatever frontend javascript libraries or frameworks you want, or none!

webpack example using plain javascript
graphiql 2.x RFC example using react 16
live demo of the monaco webpack example (prompts for github access token!)

NOTE: This is in pre-release state as we build towards GraphiQL 2.0.x. codemirror-graphql has more features (such as JSON variables validation) and is more stable.

Features

It provides the following features while editing GraphQL files:

Code completion (schema driven)
Hover (schema driven)
Validation (schema driven)
Formatting - using prettier
Syntax Highlighting
Configurable schema loading (or custom) - only handles a single schema currently
Configurable formatting options
Providing external fragments

Usage

For now, we use language id of graphql until we can ensure we can dovetail nicely with the official graphql language ID.

To use with webpack, here is an example to get you started:

yarn add monaco-graphql

Sync Example

import * as monaco from 'monaco-editor/esm/vs/editor/editor.api';

import { initializeMode } from 'monaco-graphql/esm/initializeMode';

// you can also configure these using the webpack or vite plugins for `monaco-editor`
import EditorWorker from 'worker-loader!monaco-editor/esm/vs/editor/editor.worker';
import GraphQLWorker from 'worker-loader!monaco-graphql/esm/graphql.worker';

const MonacoGraphQLAPI = initializeMode({
  schemas: [
    {
      schema: myGraphqlSchema as GraphQLSchema,
      // anything that monaco.URI.from() is compatible with
      uri: 'https://myschema.com',
      uri: '/myschema.graphql',
      // match the monaco file uris for this schema.
      // accepts specific uris and anything `picomatch` supports.
      // (everything except bracket regular expressions)
      fileMatch: ['**/*.graphql'],
      // note: not sure if ^ works if the graphql model is using urls for uris?
    },
  ],
});

window.MonacoEnvironment = {
  getWorker(_workerId: string, label: string) {
    if (label === 'graphql') {
      return new GraphQLWorker();
    }
    return new EditorWorker();
  },
};
monaco.editor.create(document.getElementById('someElementId'), {
  value: 'query { }',
  language: 'graphql',
  formatOnPaste: true,
});

Lazy Example

The existing API works as before in terms of instantiating the schema

import * as monaco from 'monaco-editor/esm/vs/editor/editor.api';

// enables our language workern right away, despite no schema
import 'monaco-graphql';

// you can also configure these using the webpack or vite plugins for `monaco-editor`
import EditorWorker from 'worker-loader!monaco-editor/esm/vs/editor/editor.worker';
import GraphQLWorker from 'worker-loader!monaco-graphql/esm/graphql.worker';

// lazily invoke the api config methods whenever we want!
monaco.languages.graphql.setSchemaConfig([
  {
    schema: myGraphqlSchema as GraphQLSchema,
    // anything that monaco.URI.from() is compatible with
    uri: 'https://myschema.com',
    uri: '/myschema.graphql',
    // match the monaco file uris for this schema.
    // accepts specific uris and anything `picomatch` supports.
    // (everything except bracket regular expressions)
    fileMatch: ['**/*.graphql'],
    // note: not sure if ^ works if the graphql model is using urls for uris?
  },
]);

window.MonacoEnvironment = {
  getWorker(_workerId: string, label: string) {
    if (label === 'graphql') {
      return new GraphQLWorker();
    }
    return new EditorWorker();
  },
};
monaco.editor.create(document.getElementById('someElementId'), {
  value: 'query { }',
  language: 'graphql',
  formatOnPaste: true,
});

This will cover the basics, making an HTTP POST with the default introspectionQuery() operation. To customize the entire fetcher, see advanced customization below. For more customization options, see the Monaco Editor API Docs

Advanced Usage

Variables JSON Support!

In monaco-graphql@0.5.0 we introduced a method getVariablesJSONSchema that allows you to retrive a JSONSchema description for the declared variables for any given set of operations

Full Sync Demo with Variables JSON

import * as monaco from 'monaco-editor/esm/vs/editor/editor.api';

import { initializeMode } from 'monaco-graphql/esm/initializeMode';

import EditorWorker from 'worker-loader!monaco-editor/esm/vs/editor/editor.worker';
import GraphQLWorker from 'worker-loader!monaco-graphql/esm/graphql.worker';

window.MonacoEnvironment = {
  getWorker(_workerId: string, label: string) {
    if (label === 'graphql') {
      return new GraphQLWorker();
    }
    return new EditorWorker();
  },
};

// the language service will be instantiated once the schema is available
  const MonacoGraphQLAPI = initializeMode({
    schemas: [{
      // anything that monaco.URI.from() is compatible with
      uri: 'https://myschema.com',
      // match the monaco file uris for this schema.
      // accepts specific filenames and anything `picomatch` supports.
      fileMatch: ["**/*.graphql"],
      schema: myGraphqlSchema as GraphQLSchema
    }],
  })


const operationModel  = monaco.editor.createModel(
  'query {}',
  'graphql',
  '/operation.graphql',
);

const operationEditor = monaco.editor.create(
  document.getElementById('someElementId'),
  {
    model: operationModel,
    language: 'graphql',
    formatOnPaste: true,
  },
);

const variablesSchemaUri = monaco.editor.URI.file('/variables-schema.json');

const variablesModel = monaco.editor.createModel(
  '{}',
  'json',
  '/variables.json',
);

const variablesEditor = monaco.editor.create(
  document.getElementById('someElementId'),
  {
    model: variablesModel,
    language: 'graphql',
    formatOnPaste: true,
  },
);

  // high-level method for configuring json variables validation
  MonacoGraphQLAPI.setDiagnosticSettings({
    validateVariablesJson: {
      // Urls, uris, anything that monaco.URI.from() is compatible with.
      // Match operation model to variables editor,
      // and the language service will automatically listen for changes,
      // and compute the json schema using the GraphQLWorker.
      // This is in the main process is applied to the global monaco json settings
      // for validation, completion and more using monaco-json's built-in JSON Schema support.
      [operationModel.uri.toString()]: [variablesModel.uri.toString()]
    },
    jsonDiagnosticSettings: {
      allowComments: true, // allow json, parse with a jsonc parser to make requests
    }
  })
  // TODO: document manual alternative approach
})();

You can also experiment with the built-in I think jsonc? (MSFT json5-ish syntax, for tsconfig.json etc) and the 3rd party monaco-yaml language modes for completion of other types of variable input. you can also experiment with editor methods to parse detected input into different formats, etc (yaml pastes as json, etc)

You could of course prefer to generate a jsonschema form for variables input using a framework of your choice, instead of an editor. Enjoy!

`MonacoGraphQLAPI` (typedoc)

If you call any of these API methods to modify the language service configuration at any point at runtime, the webworker will reload relevant language features. If you import 'monaco-graphql' synchronously, you can access the api via monaco.languages.graphql.api.

Otherwise, you can, like in the sync demo above:

import { initializeMode } from 'monaco-graphql/esm/initializeMode';
const api = intializeMode(config);

`monaco.languages.graphql.api.setSchemaConfig()`

same as the above, except it overwrites the entire schema config

monaco.languages.graphql.api.setSchemaConfig([
  {
    schema: GraphQLSchema,
    fileMatch: ['**/*.graphql'],
    uri: 'myschema.graphql',
  },
]);

`monaco.languages.graphql.api.setModeConfiguration()`

This is where you can toggle monaco language features. all are enabled by default.

monaco.languages.graphql.api.setModeConfiguration({
  documentFormattingEdits: true,
  completionItems: true,
  hovers: true,
  documentSymbols: true,
  diagnostics: true,
});

`monaco.languages.graphql.api.setFormattingOptions()`

this accepts an object { prettierConfig: prettier.Options }, which accepts any prettier option. it will not re-load the schema or language features, however the new prettier options will take effect.

this method overwrites the previous configuration, and will only accept static values that can be passed between the main/worker process boundary.

monaco.languages.graphql.api.setFormattingOptions({
  // if you wanna be like that
  prettierOptions: { tabWidth: 2, useTabs: true },
});

`monaco.languages.graphql.api.setExternalFragmentDefintions()`

Append external fragments to be used by autocomplete and other language features.

This accepts either a string that contains fragment definitions, or TypeDefinitionNode[]

`monaco.languages.graphql.api.getDiagnosticOptions`

monaco.languages.graphql.api.setDiagnosticSettings({
  validateVariablesJson: {
    // Urls, uris, anything that monaco.URI.from() is compatible with.
    // Match operation model to variables editor,
    // and the language service will automatically listen for changes,
    // and compute the json schema using the GraphQLWorker.
    // This is in the main process is applied to the global monaco json settings
    // for validation, completion and more using monaco-json's built-in JSON Schema support.
    [operationModel.uri.toString()]: [variablesModel.uri.toString()],
  },
  jsonDiagnosticSettings: {
    allowComments: true, // allow json, parse with a jsonc parser to make requests
  },
});

Webpack Usage

you'll need to refer to the webpack configuration in the full monaco webpack example for this example to work in webpack.

more examples coming soon!

Custom Webworker (for passing non-static config to worker)

If you want to pass a custom parser and/or schema fetching module, it is supported, however the setup is a bit more complicated.

You can add any LanguageServiceConfig (typedoc) configuration options you like here to languageConfig as below.

This is because we can't pass non-static configuration to the existing worker programatically, so you must import these and build the worker custom with those functions. Part of the (worthwile) cost of crossing runtimes!

you'll want to create your own mygraphql.worker.ts file, and add your custom config such as schemaLoader to createData:

import type { worker as WorkerNamespace } from 'monaco-editor';
// @ts-ignore
import * as worker from 'monaco-editor/esm/vs/editor/editor.worker';

import { GraphQLWorker } from 'monaco-graphql/esm/GraphQLWorker';

import { myValidationRules } from './custom';

self.onmessage = () => {
  try {
    worker.initialize(
      (
        ctx: WorkerNamespace.IWorkerContext,
        createData: monaco.languages.graphql.ICreateData,
      ) => {
        createData.languageConfig.customValidationRules = myValidationRules;
        return new GraphQLWorker(ctx, createData);
      },
    );
  } catch (err) {
    throw err;
  }
};

then, in your application:

import EditorWorker from 'worker-loader!monaco-editor/esm/vs/editor/editor.worker';

// specify the path to your language worker
import GraphQLWorker from 'worker-loader!./mygraphql.worker';

window.MonacoEnvironment = {
  getWorker(_workerId: string, label: string) {
    if (label === 'graphql') {
      return new GraphQLWorker();
    }
    return new EditorWorker();
  },
};

Monaco Editor Tips

If you are familiar with Codemirror/Atom-era terminology and features, here's some gotchas:

"hinting" => "code completion" in LSP terminology
"linting" => "diagnostics" in lsp terminology
the default keymap is different, more vscode like
command palette and right click context menu are important
you can extend the standard completion/linting/etc provided. for example, editor.setModelMarkers()
Monaco Editor API Docs
Monaco Editor Samples repository is great for tips on implementing with different bundlers, runtimes, etc

TODO

[x] variables JSON validation
[x] variables completion
[ ] Symbols & Definitions
[x] file uri-driven schema loading
[x] op -> schema & schema -> schema references
[x] additionalInsertText for field and argument completion

Current Tags

1.2.4-alpha.0 ... alpha (a year ago)
1.5.3-canary-8432eb69.0 ... canary (4 months ago)
1.5.2 ... latest (5 months ago)
0.3.1-alpha.3 ... next (4 years ago)

199 Versions

1.5.3-canary-8432eb69.0 ... 4 months ago
1.5.3-canary-92c2fc51.0 ... 4 months ago
1.5.2 ... 5 months ago
1.5.2-canary-1e0022eb.0 ... 6 months ago
1.5.1 ... 9 months ago
1.5.0 ... 10 months ago
1.4.1-canary-36f0bac1.0 ... 10 months ago
1.4.0 ... a year ago
1.3.1-canary-5e93a7b3.0 ... a year ago
1.3.1-canary-decdad6d.0 ... a year ago
1.3.1-canary-52ff4ca9.0 ... a year ago
1.3.1-canary-2ac8c056.0 ... a year ago
1.3.1-canary-31ca6bfa.0 ... a year ago
1.3.1-canary-21ee6a0e.0 ... a year ago
1.3.0 ... a year ago
2.0.0-canary-6ba9ba38.0 ... a year ago
2.0.0-canary-e0e2c15a.0 ... a year ago
2.0.0-canary-9eb9e2fb.0 ... a year ago
2.0.0-canary-de420cd7.0 ... a year ago
2.0.0-canary-2b03fdd0.0 ... a year ago
2.0.0-canary-298f53ab.0 ... a year ago
2.0.0-canary-cd4cdaba.0 ... a year ago
2.0.0-canary-f5830f58.0 ... a year ago
2.0.0-canary-a9e38be1.0 ... a year ago
2.0.0-canary-dfb20ee6.0 ... a year ago
2.0.0-canary-6610f112.0 ... a year ago
2.0.0-canary-d38d8126.0 ... a year ago
2.0.0-canary-d86e51b8.0 ... a year ago
2.0.0-canary-3e72a1f9.0 ... a year ago
2.0.0-canary-30653157.0 ... a year ago
2.0.0-canary-f648417e.0 ... a year ago
2.0.0-canary-344df134.0 ... a year ago
2.0.0-canary-b5674a4f.0 ... a year ago
2.0.0-canary-f0f5afb3.0 ... a year ago
2.0.0-canary-a08e9aea.0 ... a year ago
2.0.0-canary-351ba549.0 ... a year ago
2.0.0-canary-6bb88229.0 ... a year ago
2.0.0-canary-a6d20235.0 ... a year ago
2.0.0-canary-d4eae891.0 ... a year ago
2.0.0-canary-6de7e53f.0 ... a year ago
2.0.0-canary-d52fbc57.0 ... a year ago
2.0.0-canary-38c2c299.0 ... a year ago
2.0.0-canary-5d4865df.0 ... a year ago
1.2.4 ... a year ago
1.2.5-canary-88c53ea4.0 ... a year ago
1.2.5-canary-a97151b3.0 ... a year ago
1.2.5-canary-943fcbde.0 ... a year ago
1.2.5-canary-73a4ac55.0 ... a year ago
1.2.5-canary-70c9456e.0 ... a year ago
1.2.5-canary-f5992ff0.0 ... a year ago
1.2.5-canary-8d17bd3c.0 ... a year ago
1.2.5-canary-0b758ed3.0 ... a year ago
1.2.5-canary-5a3b95d3.0 ... a year ago
1.2.5-canary-b6d81c61.0 ... a year ago
1.2.5-canary-a8496344.0 ... a year ago
1.2.5-canary-8f7aa55c.0 ... a year ago
1.2.5-canary-df664982.0 ... a year ago
1.2.5-canary-8cc6cc6c.0 ... a year ago
1.2.5-canary-0ef186a2.0 ... a year ago
1.2.5-canary-6698dc22.0 ... a year ago
1.2.5-canary-2f7f1266.0 ... a year ago
1.2.5-canary-616f8a33.0 ... a year ago
1.2.4-alpha.0 ... a year ago
1.2.3 ... 2 years ago
1.2.2 ... 2 years ago
1.2.1 ... 2 years ago
1.2.0 ... 2 years ago
1.1.9-canary-1fb24baf.0 ... 2 years ago
1.1.9-canary-3928d993.0 ... 2 years ago
1.2.0-canary-fd50d2d1.0 ... 2 years ago
1.1.8 ... 2 years ago
1.1.7 ... 2 years ago
1.1.6 ... 2 years ago
1.1.6-canary-c3ab8cb3.0 ... 2 years ago
1.1.5 ... 2 years ago
1.1.4 ... 2 years ago
1.1.4-canary-27ecf339.0 ... 2 years ago
1.1.4-canary-7d147578.0 ... 2 years ago
1.1.4-canary-6b5ad5f3.0 ... 2 years ago
1.1.4-canary-a593ca85.0 ... 2 years ago
1.1.4-canary-229a9a9b.0 ... 2 years ago
1.1.4-canary-0e3571ca.0 ... 2 years ago
1.1.3 ... 2 years ago
1.1.3-canary-0ac0349e.0 ... 2 years ago
1.1.2 ... 2 years ago
1.1.2-canary-4bf7a139.0 ... 2 years ago
1.1.1 ... 2 years ago
1.1.1-canary-6f259838.0 ... 2 years ago
1.1.1-canary-85c69db3.0 ... 2 years ago
1.1.0 ... 2 years ago
1.0.17 ... 3 years ago
1.0.16 ... 3 years ago
1.0.15 ... 3 years ago
1.0.15-canary-63a8a0dd.0 ... 3 years ago
1.0.15-canary-fb52a553.0 ... 3 years ago
1.0.14 ... 3 years ago
1.0.14-canary-8291af32.0 ... 3 years ago
1.0.13 ... 3 years ago
1.0.13-canary-9e6d341c.0 ... 3 years ago
1.0.12 ... 3 years ago
1.0.12-canary-8fa698e7.0 ... 3 years ago
1.0.11 ... 3 years ago
1.0.11-canary-1c638ec3.0 ... 3 years ago
1.0.10 ... 3 years ago
1.0.9 ... 3 years ago
1.0.9-canary-75d20274.0 ... 3 years ago
1.0.9-canary-6516af96.0 ... 3 years ago
1.0.8 ... 3 years ago
1.0.8-canary-1a98e3f5.0 ... 3 years ago
1.0.7 ... 3 years ago
1.0.7-canary-05b863ab.0 ... 3 years ago
1.0.6 ... 3 years ago
1.0.6-canary-9129bfb9.0 ... 3 years ago
1.0.6-canary-59e81306.0 ... 3 years ago
1.0.6-canary-ef62e913.0 ... 3 years ago
1.0.6-canary-97ac6815.0 ... 3 years ago
1.0.6-canary-947b1d76.0 ... 3 years ago
1.0.5 ... 3 years ago
1.0.5-canary-b8d145d7.0 ... 3 years ago
1.0.5-canary-b96f3d10.0 ... 3 years ago
1.0.5-canary-312f863b.0 ... 3 years ago
1.0.4 ... 3 years ago
1.0.4-canary-5edec51e.0 ... 3 years ago
1.0.4-canary-75bdc860.0 ... 3 years ago
1.0.3 ... 3 years ago
1.0.3-canary-29be15fb.0 ... 3 years ago
1.0.3-canary-f20fe1e2.0 ... 3 years ago
1.0.2 ... 3 years ago
1.0.2-canary-07e866d1.0 ... 3 years ago
1.0.2-canary-166ffd7a.0 ... 3 years ago
1.0.2-canary-a19d0748.0 ... 3 years ago
1.0.2-canary-07a2840d.0 ... 3 years ago
1.0.2-canary-35604620.0 ... 3 years ago
1.0.2-canary-2f2c1b4d.0 ... 3 years ago
1.0.2-canary-ab0be4f0.0 ... 3 years ago
1.0.2-canary-ec866cba.0 ... 3 years ago
1.0.2-canary-742288e7.0 ... 3 years ago
1.0.2-canary-bdd62cc3.0 ... 3 years ago
1.0.2-canary-b9c71c81.0 ... 3 years ago
1.0.1 ... 3 years ago
1.0.1-canary-75700e01.0 ... 3 years ago
1.0.0 ... 3 years ago
2.0.0-canary-aba5a940.0 ... 3 years ago
1.0.0-canary-343f1670.0 ... 3 years ago
0.7.0-canary-1d118d28.0 ... 3 years ago
0.7.0-canary-8af33604.0 ... 3 years ago
0.6.6-canary-0b6fa337.0 ... 3 years ago
0.6.6-canary-033a43d2.0 ... 3 years ago
0.6.6-canary-0d171c9c.0 ... 3 years ago
0.6.6-canary-321acad7.0 ... 3 years ago
0.7.0-canary-1a140c54.0 ... 3 years ago
0.7.0-canary-b5aba87e.0 ... 3 years ago
0.7.0-canary-fae7d199.0 ... 3 years ago
0.6.6-canary-eb5c4300.0 ... 3 years ago
0.6.5 ... 3 years ago
0.6.5-canary-48f9cb01.0 ... 3 years ago
0.6.5-canary-8ce9e283.0 ... 3 years ago
0.6.5-canary-325c04b9.0 ... 3 years ago
0.6.5-canary-fea49557.0 ... 3 years ago
0.6.5-canary-412904c6.0 ... 3 years ago
0.6.5-canary-58e99aa6.0 ... 3 years ago
0.6.5-canary-6f6c49b0.0 ... 3 years ago
0.6.5-canary-3dcdd158.0 ... 3 years ago
0.6.4 ... 3 years ago
0.6.4-canary-1d1d33de.0 ... 3 years ago
0.6.3 ... 3 years ago
0.6.2 ... 3 years ago
0.6.2-canary-98364dae.0 ... 3 years ago
0.6.2-canary-3410d799.0 ... 3 years ago
0.7.0-canary-efc41fcd.0 ... 3 years ago
0.7.0-canary-86c05353.0 ... 3 years ago
0.7.0-canary-86d7df95.0 ... 3 years ago
0.7.0-canary-26511707.0 ... 3 years ago
0.7.0-canary-669af9ec.0 ... 3 years ago
0.7.0-canary-dcd21ef1.0 ... 3 years ago
0.7.0-canary-66346cbd.0 ... 3 years ago
0.6.1 ... 3 years ago
0.6.0 ... 3 years ago
0.5.1 ... 3 years ago
0.5.0 ... 3 years ago
0.4.4 ... 3 years ago
0.4.3 ... 4 years ago
0.4.2 ... 4 years ago
0.4.1 ... 4 years ago
0.4.0 ... 4 years ago
0.3.5 ... 4 years ago
0.3.4 ... 4 years ago
0.3.3 ... 4 years ago
0.3.2 ... 4 years ago
0.3.1 ... 4 years ago
0.3.1-alpha.3 ... 4 years ago
0.3.1-alpha.2 ... 4 years ago
0.3.1-alpha.1 ... 4 years ago
0.3.1-alpha.0 ... 4 years ago
0.3.0 ... 4 years ago
0.2.0 ... 4 years ago
0.1.4 ... 4 years ago
0.1.2 ... 4 years ago
0.1.1 ... 4 years ago