Skip to content

Commit b794e44

Browse files
JakeDawkinsJakeDawkins
committed
update readme with edited copy
1 parent 4184402 commit b794e44

1 file changed

Lines changed: 106 additions & 31 deletions

File tree

‎packages/vscode-apollo/README.md‎

Lines changed: 106 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,154 @@
1-
By design, GraphQL has the ability to create incredible developer experiences thank's to its strongly typed schema and query language. The Apollo GraphQL Platform brings these possibilities to life with deep editor integrations in Apollo GraphQL for VS Code. This extension brings an all-in-one tooling experience for developing apps with Apollo, including features like...
1+
# Apollo GraphQL for VS Code
22

3+
GraphQL has the potential to create incredible developer experiences, thanks to its strongly typed schema and query language. The Apollo platform brings these possibilities to life by enhancing your editor with rich metadata from your graph API.
4+
5+
![demo](./images/marketplace/jump-to-def.gif)
6+
7+
The Apollo GraphQL extension for VS Code brings an all-in-one tooling experience for developing apps with Apollo.
8+
9+
- Add [syntax highlighting](#syntax) for GraphQL files and gql templates inside JavaScript files
310
- Get instant feedback and [intelligent autocomplete](#autocomplete) for fields, arguments, types, and variables as you write queries
411
- Seamlessly manage your client side schema alongside your remote one
512
- [See performance information](#performance-insights) inline with your query definitions
6-
- Load GraphQL schemas and queries automatically from an Apollo Config file
7-
- Add [syntax highlighting](#syntax) for GraphQL files and gql templates inside JavaScript files
8-
- Detect and load client-side schemas and validates client side field usage in operations
13+
- Validate field and argument usage in operations
914
- [Navigate projects](#navigating-projects) easier with jump-to and peek-at definitions and more
10-
- Manage local and client-only schemas
15+
- Manage [client-only](#client-only-schemas) schemas
1116
- [Switch schema tags](#commands) to work on upcoming features
12-
- And more...
1317

14-
<img src="./images/marketplace/jump-to-def.gif" width="80%" style="margin: 5%" alt="Using jump to definition on a fragment">
18+
<h2 id="getting-started">Getting started</h2>
1519

16-
<h2 id="getting-started">Getting Started</h2>
20+
Some features of this extension (like syntax highlighting) will work without any configuration, but to get all of the benefits of the VS Code experience, its 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](https://www.apollographql.com/docs/platform/schema-registry.html#setup) to the Apollo schema registry. Once that is done, two steps are needed:
1721

18-
To get started, first **install the Apollo GraphQL extension**. After installation, GraphQL syntax highlighting should automatically be enabled for `.graphql`, `.gql`, `.js` and `.ts` file types.
22+
1. Create an `apollo.config.js` at the root of the project
23+
2. Copy an API key from the Engine dashboard of the published service
1924

20-
To enable more features, projects need an `apollo.config.js` file. For more info on setting up an apollo project, check out the [editor plugin docs](https://www.apollographql.com/docs/platform/editor-plugins.html).
25+
<h3 id="apollo-config">Setting up an Apollo config</h3>
2126

22-
<h2 id="features">Features</h2>
27+
In order 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:
2328

24-
Apollo for VS Code brings many helpful features for working on a GraphQL project.
29+
```js
30+
module.exports = {
31+
client: {
32+
service: "my-graphql-app"
33+
}
34+
};
35+
```
2536

26-
<h3 id="syntax">Syntax highlighting</h3>
37+
The service name is the id of the service created in Engine and can be found in the services dashboard of [Engine](https://engine.apollographql.com)
2738

28-
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 for `.graphql`, `.gql`, `.js` and `.ts` file types!
39+
> Important note: If the name of the service in Engine is changed, this value should be the service id. This can be found in the url when browsing the service in Engine. This will be easier to manage in the near future
40+
41+
<h3 id="api-key">Setting up an API key</h3>
42+
To authenticate with Engine to pull down the schema, create a file next to the `apollo.config.js` called `.env`. This should be an untraced file (i.e. don't push it to GitHub). Go to the settings page of the published service and create a new API key.
43+
44+
> 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
45+
46+
After the key is found, add the following line to the `.env` file:
47+
48+
```bash
49+
ENGINE_API_KEY=<enter copied key here>
50+
```
51+
52+
After this is done, VS Code can be restarted and the editor integration will start providing autocomplete, validation, and more!
53+
54+
<h3 id="local-schemas">Local schemas</h3>
55+
56+
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:
57+
58+
```js
59+
module.exports = {
60+
client: {
61+
service: {
62+
name: "my-graphql-app",
63+
url: "http://localhost:4000/graphql"
64+
}
65+
}
66+
};
67+
```
68+
69+
> Linking to the local schema won't provide all features such as switching schema tags and performance metrics.
70+
71+
More information about configuring an Apollo project can be found [here](https://www.apollographql.com/docs/references/apollo-config.html)
72+
73+
<h3 id="client-only-schemas">Client-only schemas</h3>
74+
75+
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 files under `./src` to find both the operations and schema definitions for building a complete schema for the application.
76+
77+
Client side schema definitions can be spread throughout the client app project and will be merged together to create one single schema. If the default behavior isn't ideal, this can be controlled through the `apollo.config.js` at the root of the project:
78+
79+
```js
80+
module.exports = {
81+
client: {
82+
service: "my-graphql-app"
83+
includes: ["./src/**/*.js"],
84+
excludes: ["**/__tests__/**"]
85+
}
86+
}
87+
```
88+
89+
<h3 id="get-the-extension">Get the extension</h3>
90+
91+
Once you have a config set up and a schema published, **install the Apollo GraphQL extension** by using this [link](https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo) or by searching `Apollo` in the VS Code extension marketplace. After installation, try opening a file containing a GraphQL operation.
92+
93+
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.
94+
95+
<img src="./images/marketplace/stats.gif" alt="Clicking the status bar icon to open the output pane">
96+
97+
<h2 id="features">Features</h2>
98+
99+
Apollo for VS Code brings many helpful features for working on a GraphQL project.
29100

30101
<h3 id="autocomplete">Intelligent autocomplete</h3>
31102

32-
Once configured, editors have full knowledge of the schema clients are running operations against, including client-only schemas (for things like local state mutations). Because of this, editors have the ability to autocomplete fields and arguments as you type.
103+
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.
33104

34-
<img src="./images/marketplace/autocomplete.gif" width="80%" style="margin: 5%" alt="vscode completing a field when typing">
105+
<img src="./images/marketplace/autocomplete.gif" alt="vscode completing a field when typing">
35106

36107
<h3 id="errors-and-warnings">Inline errors and warnings</h3>
37108

38-
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.
109+
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 right in your editor, ensuring all developers are working with the most up-to-date production schemas.
39110

40-
<img src="./images/marketplace/warnings-and-errors.gif" width="80%" style="margin: 5%" alt="tooltip showing a field deprecation warning and error">
111+
<img src="./images/marketplace/warnings-and-errors.gif" alt="tooltip showing a field deprecation warning and error">
41112

42113
<h3 id="field-type-info">Inline field type information</h3>
43114

44-
Because of GraphQL's strongly-typed schema, editors not only know about 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.
115+
Because of GraphQL's strongly-typed schema, VS Code not only know about 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.
45116

46-
<img src="./images/marketplace/type-info.png" width="80%" style="margin: 5%" alt="a tooltip showing a Boolean type for a field">
117+
<img src="./images/marketplace/type-info.png" style="max-width:800px;" alt="a tooltip showing a Boolean type for a field">
47118

48119
<h3 id="performance-insights">Performance insights</h3>
49120

50-
GraphQL operations provide incredible flexibilty in what data is requested from a service. This can sometimes lead to unknown performance characteristics of how an operation will run. Thanks to the trace wharehouse in the Apollo GraphQL Platform, teams no longer will be surprised by how long an operation takes.
121+
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 altogether by instantly seeing the cost of a query right in their editor.
122+
123+
To turn on tracing for your GraphQL server, please visit our [guide](https://www.apollographql.com/docs/platform/setup-analytics.html).
51124

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

54-
<img src="./images/marketplace/perf-annotation.png" width="80%" style="margin: 5%" alt="Performance annotation next to a field">
127+
<img src="./images/marketplace/perf-annotation.png" style="max-width:800px;" alt="Performance annotation next to a field">
55128

56-
<h3 id="jump-to-def">Jump to definition</h3>
129+
<h3 id="syntax">Syntax highlighting</h3>
130+
131+
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 for `.graphql`, `.gql`, `.js` and `.ts` file types!
57132

58-
Navigating large codebases can be difficult. In GraphQL projects, fragments of an operation may be shared throughout the project. Rather than navigating imports to find fragment definitions, the Apollo extension lets developers jump straight to it. Just command + click (mac) on a fragment to go to its definition.
133+
<h3 id="navigating-projects">Navigating projects</h3>
59134

60-
<img src="./images/marketplace/jump-to-def.gif" width="80%" style="margin: 5%" alt="Using jump to definition on a fragment">
135+
Navigating large codebases can be difficult, but the Apollo GraphQL extension makes this easier than ever. 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. Searching a project for any occurrence of a certain field is now a thing of the past!
61136

62-
<h3 id="commands">Apollo commands</h3>
63-
The VS Code extension integrates with the VS Code command palate and provides two commands currently:
137+
<img src="./images/marketplace/jump-to-def.gif" alt="Using jump to definition on a fragment">
64138

65-
- switch schema tags
66-
- reload the schema and diagnostics
139+
<h3 id="commands">Schema tag switching</h3>
67140

68-
These can be run by typing `cmd+shift+p` then typing `apollo` into thr prompt. That will show the two commands which can help teams stay on top of changes to the schema right in their editors
141+
The Apollo GraphQL platform supports publishing multiple versions (tags) of a schema. This is useful for developing on a future development schema and preparing your clients to conform to that schema. To choose another schema tag, open the Command Palette (`cmd + shift + p` on mac), search "Apollo" and choose the "Apollo: Select Schema Tag" option.
69142

70143
<h2 id="troubleshooting">Troubleshooting</h2>
71144

72145
The most common errors are configuration errors, like a missing `.env` file or incorrect service information in the `apollo.config.js` file.
73146
There is more information about configuring an Apollo projects [here](https://www.apollographql.com/docs/references/apollo-config.html).
74147

148+
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.
149+
75150
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.
76151

77-
<img src="./images/marketplace/stats.gif" width="80%" style="margin: 5%" alt="Clicking the status bar icon to open the output pane">
152+
<img src="./images/marketplace/stats.gif" alt="Clicking the status bar icon to open the output pane">
78153

79154
If problems persist or the error messages are unhelpful, an [issue](https://github.com/apollographql/apollo-tooling/issues) can be opened on the `apollo-tooling` repository.

0 commit comments

Comments
 (0)
⚡