Improve graphile export docs (#2167)

graphile · Nov 4, 2024 · 3d9fd48 · 3d9fd48
2 parents d07d3c7 + 0397c47
commit 3d9fd48
Show file tree

Hide file tree

Showing 6 changed files with 477 additions and 90 deletions.
diff --git a/postgraphile/website/postgraphile/exporting-schema.md b/postgraphile/website/postgraphile/exporting-schema.md
@@ -45,7 +45,7 @@ executable schema. You'll notice that this schema does not import
 graphile-build, graphile-build-pg, etc - it just imports what it needs from
 `graphql`, `grafast` and similar runtime modules.
 
-:::warning
+:::warning For a schema to be exported, all plugins must support exporting
 
 Not all PostGraphile plugins support exporting the schema, if you use plugins
 that don't support exporting then your exported schema is likely to have
@@ -54,7 +54,7 @@ your exported schema before relying on it.
 
 :::
 
-:::warning
+:::warning Test your exported schema thoroughly
 
 Exporting a GraphQL schema is error-prone, so you should test your exported
 schema thoroughly. The main failure mode for exported schemas is runtime errors
@@ -66,9 +66,12 @@ but you should be careful to ensure that every function that will be exported
 is either wrapped with `EXPORTABLE` (with the correct args) or is from a
 declared module - see the `graphile-export` documentation.
 
+TODO: update this warning, since this is less of an issue now that
+graphile-export does its own internal consistency checks.
+
 :::
 
-:::tip
+:::tip Use your exported schema in dev and CI too
 
 If you will be exporting your GraphQL schema we **highly recommend** that you
 adopt the exported schema into every facet of your development lifecycle: you
@@ -79,15 +82,18 @@ export.
 
 :::
 
-:::tip
+:::tip Use eslint-plugin-graphile-export when writing plugins
 
 We **highly recommend** that plugin authors (both for internal project plugins
-and plugins distributed via `npm`) use the
-[eslint-plugin-graphile-export](http://www.npmjs.com/package/eslint-plugin-graphile-export)
-ESLint plugin to ensure that your methods are correctly exported. This plugin
-is still experimental so limit it to only running against your plugin code, but
-it really helps to catch a variety of issues that may prevent your schema from
-being exported correctly.
+and plugins distributed via `npm`) consult the
+[graphile-export](https://star.graphile.org/graphile-export/) documentation in
+full. In particular, you should use the
+[`eslint-plugin-graphile-export`](http://www.npmjs.com/package/eslint-plugin-graphile-export)
+rules to help ensure that the plan resolvers and similar that you add are
+themselves exportable. (This plugin is still experimental so we recommend that
+you only enable this ruleset on the files that contain PostGraphile plugins,
+and that you commit early and often so that any unintended changes to your
+codebase can be reverted.)
 
 :::
 

diff --git a/utils/website/graphile-export/eslint.md b/utils/website/graphile-export/eslint.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 4
 title: ESLint Plugin
 ---
 
@@ -18,17 +18,18 @@ yarn add eslint-plugin-graphile-export@beta
 To set up, add `"graphile-export"` to your ESLint configuration's `plugins`
 list, and `"plugin:graphile-export/recommended"` to the `extends` list:
 
-```js
-// .eslintrc.js
+```js title=".eslintrc.js"
 module.exports = {
   //...
   plugins: [
     //...
+    // highlight-next-line
     "graphile-export",
     //...
   ],
   extends: [
     //...
+    // highlight-next-line
     "plugin:graphile-export/recommended",
     //...
   ],
@@ -53,24 +54,42 @@ to:
 
 ```ts
 const add = EXPORTABLE(
-  (
-    // The dependencies:
-    a,
-  ) =>
+  // highlight-next-line
+  (a) =>
     function add(b) {
       return a + b;
     },
-  [
-    // The dependency values
-    a,
-  ],
+  // highlight-next-line
+  [a],
 );
 ```
 
 You don't need to do this yourself everywhere, the plugin will look for common
-patterns and apply the `EXPORTABLE` itself as best it can. Do carefully review
-the changes it has made.
+patterns (property names such as `resolve`, `subscribe`, `plan`,
+`subscribePlan`, `inputPlan`, `applyPlan` and so on within objects that look
+like they are probably GraphQL related) and apply the `EXPORTABLE` itself as
+best it can.
+
+:::warning Autofix is based on heuristics
+
+eslint-plugin-graphile-export will try to spot places that you've forgotten to
+add `EXPORTABLE` and will add it for you; but this is done based on heuristics
+and thus it can go wrong. You should carefully review your autofixed code to
+ensure that the plugin hasn't made any mistakes adding `EXPORTABLE` to other
+areas of your code. We recommend you only run this plugin against the parts of
+your code for which the fixes would be relevant.
+
+:::
+
+:::note Autofixed code is unformatted
+
+No accommodation for formatting has been made, it is assumed that you are using
+`prettier` or similar code formatter and thus there's no need for us to format
+the code.
+
+:::
+
+---
 
-Note: no accommodation for formatting has been made, it is assumed that you are
-using `prettier` or similar code formatter and thus there's no need for us to
-format the code.
+Will it always be this messy looking at exportable code? Lets take a look at
+the [plans for the future](./the-future.md).