Skip to content

Commit

Permalink
updated readme to remove setup guide
Browse files Browse the repository at this point in the history
  • Loading branch information
JakeDawkins committed Jan 30, 2019
1 parent 63c1a4b commit 2342485
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 85 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

- `apollo`
- Fix configuration loading and schema tag support [#925](https://github.com/apollographql/apollo-tooling/pull/925)
- `vscode-apollo`
- Updated marketplace readme, color schemes, and icon to be prettier [#942](https://github.com/apollographql/apollo-tooling/pull/942)

## `[email protected]`

Expand Down
95 changes: 10 additions & 85 deletions packages/vscode-apollo/README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,14 @@
---
title: Editor plugins
description: How to get the most out of your editor with Apollo
---
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...

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:

- Instant feedback and [intelligent autocomplete](#autocomplete) for fields, arguments, types, and variables as you write queries
- Get instant feedback and [intelligent autocomplete](#autocomplete) for fields, arguments, types, and variables as you write queries
- Seamlessly manage your client side schema alongside your remote one
- [See performance information](#performance-insights) inline with your query definitions
- Loads GraphQL schemas and queries automatically from an Apollo Config file
- Adds [syntax highlighting](#syntax) for GraphQL files and gql templates inside JavaScript files
- Detects and loads client-side schemas and validates client side field usage in operations
- [Jump-to-definition](#jump-to-def) for fragments and schema types
- Supports [local](#local-schemas) and [client-only](#client-only-schemas) schemas
- Allows [switching schema tags](#commands) to work on upcoming features
- Load GraphQL schemas and queries automatically from an Apollo Config file
- Add [syntax highlighting](#syntax) for GraphQL files and gql templates inside JavaScript files
- Detect and load client-side schemas and validates client side field usage in operations
- [Navigate projects](#navigating-projects) easier with jump-to and peek-at definitions and more
- Manage local and client-only schemas
- [Switch schema tags](#commands) to work on upcoming features
- And more...

<img src="./images/marketplace/jump-to-def.gif" width="80%" style="margin: 5%" alt="Using jump to definition on a fragment">
Expand All @@ -22,77 +17,7 @@ By design, GraphQL has the ability to create incredible developer experiences th

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.

<h3 id="linking-a-schema">Linking a schema</h2>

To get all of the benefits of the VS Code experience, its best to link the schema that is being developed against. The best way to do that is by [publishing a schema](./schema-registry.html#publish) to the Apollo schema registry. Once that is done, two steps are needed:

1. Create an `apollo.config.js` at the root of the project
2. Copy an API key from the Engine dashboard of the published service

<h3 id="apollo-config">Setting up an Apollo config</h3>
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:

```js
module.exports = {
client: {
service: "my-graphql-app"
}
};
```

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)

> 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
<h3 id="api-key">Setting up an API key</h3>
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.

> 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
After the key is found, add the following line to the `.env` file:

```bash
ENGINE_API_KEY=<enter copied key here>
```

After this is done, VS Code can be restarted and the editor integration will start providing autocomplete, validation, and more!

<h3 id="local-schemas">Local schemas</h3>

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:

```js
module.exports = {
client: {
service: {
name: "my-graphql-app",
url: "http://localhost:4000/graphql"
}
}
};
```

> Linking to the local schema won't provide all features such as switching schema tags and performance metrics.
More information about configuring an Apollo project can be found [here](../platform/apollo-config.html)

<h3 id="client-only-schemas">Client-only schemas</h3>

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.

Client side schema definitions can be spread throughout the client app project and will be merged together to create one single schema. This can be controlled through the `apollo.config.js` at the root of he project:

```js
module.exports = {
client: {
service: "my-graphql-app"
includes: ["./src/**/*.js"],
excludes: ["**/__tests__/**"]
}
}
```

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.
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).

<h2 id="features">Features</h2>

Expand Down Expand Up @@ -145,7 +70,7 @@ These can be run by typing `cmd+shift+p` then typing `apollo` into thr prompt. T
<h2 id="troubleshooting">Troubleshooting</h2>

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

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.

Expand Down

0 comments on commit 2342485

Please sign in to comment.