Apollo GraphQL for VS Code

Thanks to its strongly typed schema and query language, GraphQL has the potential to create incredible developer experiences. The Apollo platform brings these possibilities to life by enhancing your editor with rich metadata from your graph API.

The Apollo GraphQL extension for VS Code brings an all-in-one tooling experience for developing apps with Apollo.

• Add syntax highlighting for GraphQL files and gql templates inside JavaScript files
• Get instant feedback and intelligent autocomplete for fields, arguments, types, and variables as you write queries
• Manage client-side schema alongside remote schema
• See performance information inline with your query definitions
• Extra features to help you with supergraph editing
• Validate field and argument usage in operations
• Navigate projects more easily with jump-to and peek-at definitions
• Manage client-only schemas
• Switch graph variants to work with schemas running on different environments

Getting started

The VS Code plugin must be linked to a published or local schema. To do so, create an apollo.config.json file at the root of the project. Alternatively, you can create a yaml, cjs, mjs, or ts file with the same configuration.

For the contents of this configuration file, select one of these options:

Configure extension for client development with schemas published to Apollo GraphOS

{
  "client": {
    "service": "graphos-graph-name"
  }
}

APOLLO_KEY=<enter copied key here>

Configure extension for supergraph schema development

{
  "rover": {
    // optional, if your rover binary is in PATH it will automatically be detected
    "bin": "/path/to/rover",
    // optional, defaults to `supergraph.yaml` in the folder of the configuration file
    "supergraphConfig": "/path/to/supergraph.yaml",
    // optional, defaults to the Rover default profile
    "profile": ""
  }
}

{
  "rover": {}
}

Configure extension for client development with introspection from a locally running service

{
  "client": {
    "service": {
      "name": "my-graphql-app",
      "url": "http://localhost:4000/graphql"
    }
  }
}

Configure extension for client development with local schema files

{
  "client": {
    "service": {
      // can be a string pointing to a single file or an array of strings
      "localSchemaFile": "./path/to/schema.graphql"
    }
  }
}

Bonus: Adding client-only schemas

{
  "client": {
    // "service": <your service configuration>,
    // array of glob patterns
    "includes": ["./src/**/*.js"],
    // array of glob patterns
    "excludes": ["**/__tests__/**"]
  }
}

Get the extension

Once you have a config set up and a schema published, install the Apollo GraphQL extension, then try opening a file containing a GraphQL operation.

After opening a file, click the status bar icon to open the output window and see stats about the project associated with that file. This is helpful for confirming that the project is set up properly.

Features

Apollo for VS Code offers a range of useful features for working on GraphQL projects.

Intelligent autocomplete

Once configured, VS Code has full knowledge of the schema clients are running operations against, including client-only schemas (for things like local state mutations). Because of this, it have the ability to autocomplete fields and arguments as you type.

Inline errors and warnings

VS Code can use local or published schemas to validate operations before running them. Syntax errors, invalid fields or arguments, and even deprecated fields instantly appear as errors or warnings in your editor, ensuring your entire team is working with the most up-to-date production schemas.

Inline field type information

Because of GraphQL's strongly typed schema, VS Code knows not only which fields and arguments are valid, but also what types are expected. Hover over any type in a valid GraphQL operation to see what type that field returns and whether or not it can be null.

Performance insights

GraphQL's flexibility can make it difficult to predict the cost of an operation. Without insight into how expensive an operation is, developers can accidentally write queries that place strain on their graph API's underlying backends. Thanks to the Apollo platform's integration with VS Code and our trace warehouse, teams can avoid these performance issues by instantly seeing the cost of a query in their editor.

The VS Code extension will show inline performance diagnostics when connected to a service with reported metrics in GraphOS Studio. As operations are typed, any fields that take longer than 1 ms to respond will be annotated to the right of the field inline. This shows team members how long the operation will take as more and more fields are added to operations or fragments.

Syntax highlighting

Apollo's editor extension provides syntax highlighting for all things GraphQL, including schema definitions in .graphql files, complex queries in TypeScript, and even client-only schema extensions. Syntax highlighting for GraphQL works out-of-the-box in GraphQL, JavaScript, TypeScript, Python, Lua, Ruby, Dart, Elixir, and ReasonML files.

supergraph editing

The extension provides features for supergraph editing, such as support for Federation directives, subgraph-spanning go-to-definition, and reporting composition errors directly to the Problems panel.

Navigating projects

Navigating large codebases can be difficult, but the Apollo GraphQL extension makes this easier. Right-clicking on any field in operations or schemas allows you to jump to (or peek at) definitions and find any other references to that field in your project.

Schema tag switching

Apollo supports publishing multiple versions (variants) of a schema. This is useful for developing on a future development schema and preparing your clients to conform to that schema. To switch between graph variants, open the Command Palette (cmd + shift + p on mac), search "Apollo" and choose the "Apollo: Select Schema Tag" option.

Troubleshooting

The most common errors are configuration errors, like a missing .env file or incorrect service information in the apollo.config.json file. Please see the Apollo config docs for more configuration guidance.

An old version of a published schema may cause other errors. To reload a schema, open the Command Palette (cmd + shift + p on Mac), search for "Apollo." Choose the Apollo: Reload Schema option.

Sometimes, errors will appear as a notification at the bottom of your editor. Other, less critical, messages may be shown in the output pane of the editor. To open the output pane and get diagnostic information about the extension and the current service loaded (if working with a client project), click the Apollo GraphQL icon in the status bar at the bottom.

If problems persist or the error messages are unhelpful, open an issue in the vscode-graphql repository.

Additional Apollo config options

You can add these configurations to your Apollo config file.

client.tagName

Optional - custom tagged template literal.

When using GraphQL with JavaScript or TypeScript projects, it is common to use the gql tagged template literal to write out operations. Apollo tools look through your files for the gql tag to extract your queries, so if you use a different template literal, you can configure it like so:

{
  "client": {
    "tagName": "graphql",
    "service": //...
  }
}