diff --git a/src/components/Page.js b/src/components/Page.js index 9b9419c27..33df6aeec 100644 --- a/src/components/Page.js +++ b/src/components/Page.js @@ -410,7 +410,7 @@ export default function Page({file}) { whiteSpace: 'normal' } }, - '>': { + [['>', '> details >']]: { ':not(a):not(:last-child)': { mb: 6 }, diff --git a/src/content/basics/devtools/editor-plugins.mdx b/src/content/basics/devtools/editor-plugins.mdx index ed74cc275..7a14771f8 100644 --- a/src/content/basics/devtools/editor-plugins.mdx +++ b/src/content/basics/devtools/editor-plugins.mdx @@ -14,10 +14,11 @@ The Apollo [VS Code extension](https://marketplace.visualstudio.com/items?itemNa The extension enables you to: -- Add [syntax highlighting](#syntax-highlighting) for GraphQL files and `gql` templates inside JavaScript files +- Add [syntax highlighting](#syntax-highlighting) for GraphQL files and gql templates inside JavaScript files - Get instant feedback and [intelligent autocomplete](#intelligent-autocomplete) for fields, arguments, types, and variables as you write queries -- Manage client side schema alongside remote schema +- Manage client-side schema alongside remote schema - See [performance information](#performance-insights) inline with your query definitions +- Extra features to help you with [supergraph editing](#supergraph-editing) - Validate field and argument usage in operations - [Navigate projects more easily](#navigating-projects) with jump-to and peek-at definitions - Manage [client-only](#client-only-schemas) schemas @@ -25,105 +26,174 @@ The extension enables you to: ## Getting started -To get all the benefits of the VS Code experience, it's best to link the schema that is being developed against before installing the extension. The best way to do that is by [publishing a schema](/graphos/delivery/publishing-schemas/) to the Apollo schema registry. After that's done: +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. -1. Create an `apollo.config.js` file at the root of the project. - Alternatively, you can create a `cjs`, `mjs`, or `ts` file with the same configuration. -2. Obtain a [Personal API key](/graphos/api-keys) from GraphOS Studio. +For the contents of this configuration file, select one of these options: -### Setting up an Apollo config +### Configure extension for client development with schemas published to Apollo GraphOS -For the VS Code plugin to know how to find the schema, it needs to be linked to either a published schema or a local one. To link a project to a published schema, edit the `apollo.config.js` file to look like this: +
+ +Expand for instructions. + -```js -module.exports = { - client: { - service: 'my-graphql-app' +To get all the benefits of the VS Code experience, it's best to link the schema being developed before installing the extension. The best way to do that is by [publishing a schema](https://www.apollographql.com/docs/graphos/delivery/publishing-schemas/) to the [GraphOS schema registry](https://www.apollographql.com/docs/graphos#core-features). + +After that's done, edit the `apollo.config.json` file to look like this: + +```json +{ + "client": { + "service": "graphos-graph-name" } -}; +} ``` The `service` name is the name of the graph you've created in [GraphOS Studio](https://studio.apollographql.com). See [additional configuration options](#additional-apollo-config-options). -### Setting up the `.env` file - -To authenticate with GraphOS Studio to pull down your schema, create a `.env` file in the same directory as the `apollo.config.js` file. This should be an untracked file (that is, don't commit it to Git). +To authenticate with GraphOS Studio to pull down your schema, create an `.env` file in the same directory as the `apollo.config.json` file. The `.env` file should be untracked—that is, don't commit it to Git. -Then go to your [User Settings page](https://studio.apollographql.com/user-settings/api-keys?referrer=docs-content) in GraphOS Studio to create a new Personal API key. +Then, go to your [User Settings page](https://studio.apollographql.com/user-settings/api-keys?referrer=docs-content) in GraphOS Studio to create a new personal API key. -It is best practice to create a new API key for each member of the team and name the key so its easy to find and revoke if needed. This will be easier to manage in the future. +It's best practice to create a new API key for each team member. API keys should also be named so they're easy to find and revoke if needed. -After the key is found, add the following line to the `.env` file: +After you've created your API key, add the following line to the `.env` file: ```bash showLineNumbers=false APOLLO_KEY= ``` -After this is done, VS Code can be reloaded and the Apollo integration will connect to GraphOS Studio to provide autocomplete, validation, and more. +Afterward, reload VS Code. The Apollo integration will connect to GraphOS Studio to provide autocomplete, validation, and more. + +
+ +### Configure extension for supergraph schema development + +
+ +Expand for instructions. + + +The extension can integrate with the [Rover CLI](https://www.apollographql.com/docs/rover/) to help you design supergraph schemas with additional support for Apollo Federation. + +Ensure you've [installed](https://www.apollographql.com/docs/rover/getting-started) and [configured](https://www.apollographql.com/docs/rover/configuring) the [latest Rover release](https://github.com/apollographql/rover/releases). + +Next edit your `apollo.config.json` to look like this: + +```json +{ + "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": "" + } +} +``` + +Since all these options are optional, you can specify only the `rover` key to indicate you're using Rover for schema development rather than client development: + +```json +{ + "rover": {} +} +``` + +Afterward, reload VS Code. The Apollo extension will start using Rover to help you build your supergraph. + +
-### Local schemas +### Configure extension for client development with introspection from a locally running service -Sometimes it may make sense to link the editor to a locally running version of a schema to try out new designs that are in active development. To do this, the `apollo.config.js` file can be linked to a local service definition: +
+ +Expand for instructions. + -```js -module.exports = { - client: { - service: { - name: 'my-graphql-app', - url: 'http://localhost:4000/graphql' +To experiment with designs under active development, you can link the editor to a locally running version of a schema. Link the `apollo.config.json` file to a local service definition like so: + +```json +{ + "client": { + "service": { + "name": "my-graphql-app", + "url": "http://localhost:4000/graphql" } } -}; +} ``` -Linking to the local schema won't provide all features, such as switching graph variants and performance metrics. +Linking to local schemas won't provide all extension features, such as switching graph variants and performance metrics. + +
+ +### Configure extension for client development with local schema files -### Local schema files +
+ +Expand for instructions. + You might not always have a running server to link to, so the extension also supports linking to a local schema file. This is useful for working on a schema in isolation or for testing out new features. -To link to a local schema file, add the following to the `apollo.config.js` file: +To link to a local schema file, add the following to the `apollo.config.json` file: -```js -module.exports = { - client: { - service: { +```json +{ + "client": { + "service": { // can be a string pointing to a single file or an array of strings - localSchemaFile: './path/to/schema.graphql' + "localSchemaFile": "./path/to/schema.graphql" } } -}; +} ``` -### Client-only schemas +
+ +
+ +### Bonus: Adding client-only schemas -One of the best features of the VS Code extension is the automatic merging of remote schemas and local ones when using integrated state management with Apollo Client. This happens automatically whenever schema definitions are found within a client project. By default, the VS Code extension will look for all JavaScript, TypeScript and GraphQL files under `./src` to find both the operations and schema definitions for building a complete schema for the application. +
-Client side schema definitions can be spread throughout the client app project and will be merged together to create one single schema. The default behavior can be controlled by adding specifications to the `apollo.config.js`: +
+ +Expand for instructions. + -```js -module.exports = { - client: { - service: 'my-graphql-app', +One of the best features of the VS Code extension is the automatic merging of remote and local schemas when using integrated state management with Apollo Client. This happens automatically whenever schema definitions are found within a client project. By default, the VS Code extension will look for all JavaScript, TypeScript, and GraphQL files under `./src` to find both the operations and schema definitions for building a complete schema for the application. + +Client-side schema definitions can be spread throughout the client app project and will be merged to create one single schema. You can set the default behavior by adding specifications to the `apollo.config.json`: + +```json +{ + "client": { + // "service": , // array of glob patterns - includes: ['./src/**/*.js'], + "includes": ["./src/**/*.js"], // array of glob patterns - excludes: ['**/__tests__/**'] + "excludes": ["**/__tests__/**"] } -}; +} ``` +
+ ### Get the extension Once you have a config set up and a schema published, [install the Apollo GraphQL extension](https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo), then try opening a file containing a GraphQL operation. -When a file open, clicking the status bar icon will open the output window and print stats about the project associated with that file. This is helpful when confirming the project is setup properly. +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. VS Code completing a field when typing -### Inline errors and warnings +### Inline errors and ../img/editors/warnings -Editors 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 right in your editor, ensuring all developers are working with the most up-to-date production schemas. +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. Hover on Federation directive ### 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 gives you the ability to jump to (or peek at) definitions, as well as find any other references to that field in your project. +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. Using jump to definition on a fragment -### Graph variant switching +
+ +### Schema tag switching + +
-Apollo supports publishing multiple versions ([variants](/graphos/graphs/#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. +Apollo supports publishing multiple versions ([variants](https://www.apollographql.com/docs/graphos/graphs/#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.js` file. Please see [the Apollo config docs](./apollo-config/) for more configuration guidance. +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](./apollo-config/) for more configuration guidance. -Other errors may be caused from an old version of a published schema. To reload a schema, open the Command Palette (`cmd + shift + p` on mac), search "Apollo" and choose the "Apollo: Reload Schema" option. +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 show up 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), just click the "Apollo GraphQL" icon in the status bar at the bottom. +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. Clicking the status bar icon to open the output pane -If problems persist or the error messages are unhelpful, open an [issue](https://github.com/apollographql/vscode-graphql/issues) in the `vscode-graphql` repository. +If problems persist or the error messages are unhelpful, open an [issue](https://github.com/apollographql/vscode-graphql/issues) +in the `vscode-graphql` repository. ## Additional Apollo config options @@ -228,11 +314,11 @@ _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: -```js -module.exports = { - client: { - tagName: "graphql", // highlight-line - service: ... +```json +{ + "client": { + "tagName": "graphql", + "service": //... } -}; +} ``` diff --git a/src/content/basics/img/editors/federation-directive-hover.png b/src/content/basics/img/editors/federation-directive-hover.png new file mode 100644 index 000000000..0da841f01 Binary files /dev/null and b/src/content/basics/img/editors/federation-directive-hover.png differ