Improving docs on preset package

Shopify · Dec 13, 2023 · ee6c30b · ee6c30b
1 parent dd64360
commit ee6c30b
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 15 deletions.
diff --git a/.changeset/sharp-coats-argue.md b/.changeset/sharp-coats-argue.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/api-codegen-preset/README.md b/packages/api-codegen-preset/README.md
@@ -3,7 +3,7 @@
 <!-- ![Build Status]() -->
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../../LICENSE.md)
-[![npm version](https://badge.fury.io/js/%40shopify%api-codegen-preset.svg)](https://badge.fury.io/js/%40shopify%api-codegen-preset)
+[![npm version](https://badge.fury.io/js/@shopify%2Fapi-codegen-preset.svg)](https://badge.fury.io/js/@shopify%2Fapi-codegen-preset)
 
 This package enables JavaScript / TypeScript apps to use a `#graphql` tag to parse queries with [`graphql-codegen`](https://the-guild.dev/graphql/codegen).
 
@@ -41,7 +41,7 @@ This gives you complete control over your configuration if you want to set up a
 
 | Option  | Type      | Default              | Description                                                                                                                          |
 | ------- | --------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| apiType | `ApiType` |                      | The API to pull schemas from.                                                                                                        |
+| apiType | `ApiType` | *N/A*                | The API to pull schemas from.                                                                                                        |
 | module  | `string?` | Depends on `ApiType` | Change the module whose types will be overridden. Use this to override the types for any package, as long as it uses the same names. |
 
 #### Example `.graphqlrc.ts` file
@@ -52,15 +52,14 @@ import { ApiType, pluckConfig, preset } from "@shopify/api-codegen-preset";
 export default {
   // For syntax highlighting / auto-complete when writing operations
   schema: "https://shopify.dev/admin-graphql-direct-proxy",
-  documents: ["*.{js,ts,jsx,tsx}"],
+  documents: ["./**/*.{js,ts,jsx,tsx}"],
   projects: {
     default: {
+      // For type extraction
       schema: "https://shopify.dev/admin-graphql-direct-proxy",
-      documents: ["*.{js,ts,jsx,tsx}"],
+      documents: ["./**/*.{js,ts,jsx,tsx}"],
       extensions: {
         codegen: {
-          schema: "https://shopify.dev/admin-graphql-direct-proxy",
-          documents: ["*.{js,ts,jsx,tsx}"],
           // Enables support for `#graphql` tags, as well as `/* GraphQL */`
           pluckConfig,
           generates: {
@@ -92,7 +91,7 @@ Use this function if you want to configure a custom project, or add your own `ge
 
 | Option     | Type        | Default              | Description                                                                                                                          |
 | ---------- | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| apiType    | `ApiType`   |                      | The API to pull schemas from.                                                                                                        |
+| apiType    | `ApiType`   | *N/A*                | The API to pull schemas from.                                                                                                        |
 | apiVersion | `string?`   | Latest               | Pull schemas for a specific version.                                                                                                 |
 | outputDir  | `string?`   | `.`                  | Where to output the types files.                                                                                                     |
 | documents  | `string[]?` | `./**/*.{ts,tsx}`    | Glob pattern for files to parse.                                                                                                     |
@@ -136,7 +135,7 @@ This function creates a fully-functional project configuration.
 
 | Option     | Type        | Default              | Description                                                                                                                          |
 | ---------- | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| apiType    | `ApiType`   |                      | The API to pull schemas from.                                                                                                        |
+| apiType    | `ApiType`   | *N/A*                | The API to pull schemas from.                                                                                                        |
 | apiVersion | `string?`   | Latest               | Pull schemas for a specific version.                                                                                                 |
 | outputDir  | `string?`   | `.`                  | Where to output the types files.                                                                                                     |
 | documents  | `string[]?` | `./**/*.{ts,tsx}`    | Glob pattern for files to parse.                                                                                                     |
@@ -195,6 +194,7 @@ pnpm run graphql-codegen
 > [!NOTE]
 > Codegen will fail if it can't find any documents to parse.
 > To fix that, either create a query or set the [`ignoreNoDocuments` option](https://the-guild.dev/graphql/codegen/docs/config-reference/codegen-config#configuration-options) to `true`.
+> Queries and mutations must have a name for the parsing to work.
 
 Once the script parses your operations, you can mark any operations for parsing by adding the `#graphql` tag to the string.
 For example:

diff --git a/packages/api-codegen-preset/package.json b/packages/api-codegen-preset/package.json
@@ -2,12 +2,16 @@
   "name": "@shopify/api-codegen-preset",
   "version": "0.0.1",
   "description": "Preset for graphql-codegen to parse and type queries to Shopify APIs",
+  "author": "Shopify",
+  "license": "MIT",
+  "homepage": "https://github.com/Shopify/shopify-api-js/tree/main/packages/api-codegen-preset#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Shopify/shopify-api-js.git"
   },
-  "author": "Shopify",
-  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Shopify/shopify-api-js/issues"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/ts/index.d.ts",
@@ -72,9 +76,5 @@
   },
   "devDependencies": {
     "regenerator-runtime": "^0.14.0"
-  },
-  "bugs": {
-    "url": "https://github.com/Shopify/shopify-api-js/issues"
-  },
-  "homepage": "https://github.com/Shopify/shopify-api-js/packages/api-codegen-preset#readme"
+  }
 }
diff --git a/packages/shopify-api/docs/guides/graphql-types.md b/packages/shopify-api/docs/guides/graphql-types.md
@@ -73,6 +73,9 @@ pnpm run graphql-codegen
 When the script runs, it'll create a new `admin.generated.d.ts` file - or `storefront` depending on your configuration.
 The `@shopify/shopify-api` package will automatically apply the types created in those files, so your queries will have variables and return types automatically!
 
+> [!NOTE]
+> Make sure to include the `.generated.d.ts` files in your `tsconfig` `"include"` configuration for the types to load.
+
 To make your development flow faster, you can pass in the `--watch` flag to update the query types whenever you save a file:
 
 ```sh