Change default recommended configuration file format to json. (#209)

Author: phryneas

.changeset/fuzzy-fireants-exercise.md

@@ -0,0 +1,5 @@
+---
+"vscode-apollo": minor
+---
+
+Change default recommended configuration file format to `json`.

README.md

@@ -26,31 +26,35 @@ The Apollo GraphQL extension for VS Code brings an all-in-one tooling experience
 
 <h2 id="getting-started">Getting started</h2>
 
-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](https://www.apollographql.com/docs/graphos/delivery/publishing-schemas/) to the Apollo schema registry. After that's done:
+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.
 
-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](https://www.apollographql.com/docs/graphos/api-keys) from GraphOS Studio.
+First, 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.
 
-<h3 id="apollo-config">Setting up an Apollo config</h3>
+For the contents of this configuration file, select one of these options:
 
-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:
+<details>
+<summary>
+<h3>Configure extension for schemas published to Apollo GraphOS</h3>
+</summary>
 
-```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 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/graphos/delivery/publishing-schemas/) to the Apollo schema registry.
+
+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).
 
-<h3 id="api-key">Setting up the <code>.env</code> file</h3>
-
-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 a `.env` file in the same directory as the `apollo.config.json` file. This should be an untracked file (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.
 
@@ -64,56 +68,68 @@ APOLLO_KEY=<enter copied key here>
 
 After this is done, VS Code can be reloaded and the Apollo integration will connect to GraphOS Studio to provide autocomplete, validation, and more.
 
-<h3 id="local-schemas">Local schemas</h3>
+</details>
+
+<details>
+<summary>
+<h3 id="local-schemas">Configure extension to use introspection from a locally running service</h3>
+</summary>
 
-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:
+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.json` file can be linked to a local service definition:
 
-```js
-module.exports = {
-  client: {
-    service: {
-      name: "my-graphql-app",
-      url: "http://localhost:4000/graphql",
-    },
-  },
-};
+```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.
 
-<h3 id="local-schema-files">Local schema files</h3>
+</details>
+
+<details>
+<summary>
+<h3 id="local-schema-files">Configure extension for local schema files</h3>
+</summary>
 
 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"
+    }
+  }
+}
 ```
 
-<h3 id="client-only-schemas">Client-only schemas</h3>
+</details>
+
+<h3 id="client-only-schemas">Adding 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. 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`:
+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.json`:
 
-```js
-module.exports = {
-  client: {
-    service: "my-graphql-app",
+```json
+{
+  "client": {
+    // "service": <your service configuration>,
     // array of glob patterns
-    includes: ["./src/**/*.js"],
+    "includes": ["./src/**/*.js"],
     // array of glob patterns
-    excludes: ["**/__tests__/**"],
-  },
-};
+    "excludes": ["**/__tests__/**"]
+  }
+}
 ```
 
 <h3 id="get-the-extension">Get the extension</h3>
@@ -195,11 +211,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": //...
   }
-};
+}
 ```

package-lock.json

@@ -48,6 +48,7 @@
     "graphql": "16.9.0",
     "graphql-language-service": "5.2.2",
     "graphql-tag": "2.12.6",
+    "jsonc-parser": "^3.3.1",
     "lodash.debounce": "4.0.8",
     "lodash.merge": "4.6.2",
     "lodash.throttle": "4.1.1",
@@ -150,6 +151,12 @@
           "GraphQL"
         ],
         "configuration": "./graphql.configuration.json"
+      },
+      {
+        "id": "jsonc",
+        "filenames": [
+          "apollo.config.json"
+        ]
       }
     ],
     "grammars": [

package.json

@@ -1,8 +1,9 @@
 {
   "client": {
     "service": {
+      // test
       "name": "localMultiSchema",
       "localSchemaFile": ["./starwarsSchema.graphql", "./planets.graphql"]
     }
   }
-}
+}

sampleWorkspace/localSchemaArray/apollo.config.json

@@ -28,6 +28,7 @@ async function main() {
       /* add to the end of plugins array */
       esbuildProblemMatcherPlugin,
       buildJsonSchemaPlugin,
+      resolvePlugin,
     ],
   });
   if (watch) {
@@ -90,6 +91,18 @@ const buildJsonSchemaPlugin = {
   },
 };
 
+const resolvePlugin = {
+  name: "resolve",
+  setup(build) {
+    build.onResolve(
+      { filter: /^jsonc-parser$/ },
+      async ({ path, ...options }) => {
+        return build.resolve("jsonc-parser/lib/esm/main.js", options);
+      },
+    );
+  },
+};
+
 main().catch((e) => {
   console.error(e);
   process.exit(1);

src/build.js

@@ -217,7 +217,7 @@ client:
 
     it("loads config from a json file", async () => {
       writeFilesToDir(dir, {
-        "apollo.config.json": `{"client": {"service": "hello"} }`,
+        "apollo.config.json": `{"client": /* testing jsonc */ {"service": "hello"} }`,
       });
       const config = await loadConfig({ configPath: dirPath });
       expect(config?.client?.service).toEqual("hello");

src/language-server/config/__tests__/loadConfig.ts

@@ -1,4 +1,4 @@
-import { cosmiconfig, defaultLoaders } from "cosmiconfig";
+import { cosmiconfig, defaultLoaders, Loader } from "cosmiconfig";
 import { dirname, resolve } from "path";
 import { readFileSync, existsSync, lstatSync } from "fs";
 import {
@@ -9,6 +9,7 @@ import {
 import { getServiceFromKey } from "./utils";
 import { URI } from "vscode-uri";
 import { Debug } from "../utilities";
+import { ParseError, parse as parseJsonC } from "jsonc-parser";
 import { loadJs, loadTs } from "./loadTsConfig";
 
 // config settings
@@ -42,6 +43,19 @@ export type ConfigResult<T> = {
 
 // XXX load .env files automatically
 
+const loadJsonc: Loader = (filename, contents) => {
+  const errors: ParseError[] = [];
+  try {
+    return parseJsonC(contents, errors);
+  } finally {
+    if (errors.length) {
+      Debug.error(
+        `Error parsing JSONC file ${filename}, file might not be valid JSONC`,
+      );
+    }
+  }
+};
+
 export async function loadConfig({
   configPath,
 }: LoadConfigSettings): Promise<ApolloConfig | null> {
@@ -53,6 +67,7 @@ export async function loadConfig({
       ".mjs": loadJs,
       ".cjs": loadJs,
       ".js": loadJs,
+      ".json": loadJsonc,
     },
   });