Merge pull request #1058 from Shopify/add_sf_graphql_types

Add Storefront API GraphQL types

.changeset/clean-countries-rush.md

@@ -0,0 +1,7 @@
+---
+"@shopify/storefront-api-client": minor
+"@shopify/admin-api-client": minor
+"@shopify/graphql-client": minor
+---
+
+Added the ability to automatically type GraphQL queries to the Storefront API when the files created by @shopify/api-codegen-preset are loaded for the app.

packages/storefront-api-client/README.md

@@ -338,6 +338,54 @@ if (response.ok) {
 }
 ```
 
+## Typing variables and return objects
+
+This client is compatible with the `@shopify/api-codegen-preset` package.
+You can use that package to create types from your operations with the [Codegen CLI](https://www.graphql-cli.com/codegen/).
+
+There are different ways to [configure codegen](https://github.com/Shopify/shopify-api-js/tree/main/packages/api-codegen-preset#configuration) with it, but the simplest way is to:
+
+1. Add the preset package as a dev dependency to your project, for example:
+    ```bash
+    npm install --save-dev @shopify/api-codegen-preset
+    ```
+1. Create a `.graphqlrc.ts` file in your root containing:
+    ```ts
+    import { ApiType, shopifyApiProject } from "@shopify/api-codegen-preset";
+
+    export default {
+      schema: "https://shopify.dev/storefront-graphql-direct-proxy",
+      documents: ["*.ts", "!node_modules"],
+      projects: {
+        default: shopifyApiProject({
+          apiType: ApiType.Storefront,
+          apiVersion: "2023-10",
+          outputDir: "./types",
+        }),
+      },
+    };
+    ```
+1. Add `"graphql-codegen": "graphql-codegen"` to your `scripts` section in `package.json`.
+1. Tag your operations with `#graphql`, for example:
+    ```ts
+    const {data, errors, extensions} = await client.request(
+      `#graphql
+      query Shop {
+        shop {
+          name
+        }
+      }`
+    );
+    console.log(data?.shop.name);
+    ```
+1. Run `npm run graphql-codegen` to parse the types from your operations.
+
+> [!NOTE]
+> Remember to ensure that your tsconfig includes the files under `./types`!
+
+Once the script runs, it'll create the file `./types/storefront.generated.d.ts`.
+When TS includes that file, it'll automatically cause the client to detect the types for each query.
+
 ## Log Content Types
 
 ### `UnsupportedApiVersionLog`

packages/storefront-api-client/src/index.ts

@@ -1 +1,2 @@
 export { createStorefrontApiClient } from "./storefront-api-client";
+export { StorefrontQueries, StorefrontMutations } from "./types";

packages/storefront-api-client/src/storefront-api-client.ts

@@ -5,14 +5,13 @@ import {
   validateApiVersion,
   generateGetGQLClientParams,
   generateGetHeaders,
-  ApiClientFetch,
-  ApiClientRequest,
 } from "@shopify/graphql-client";
 
 import {
   StorefrontApiClientOptions,
   StorefrontApiClient,
   StorefrontApiClientConfig,
+  StorefrontOperations,
 } from "./types";
 import {
   DEFAULT_SDK_VARIANT,
@@ -96,25 +95,21 @@ export function createStorefrontApiClient({
   const getHeaders = generateGetHeaders(config);
   const getApiUrl = generateGetApiUrl(config, apiUrlFormatter);
 
-  const getGQLClientParams = generateGetGQLClientParams({
+  const getGQLClientParams = generateGetGQLClientParams<StorefrontOperations>({
     getHeaders,
     getApiUrl,
   });
 
-  const fetch: ApiClientFetch = (...props) => {
-    return graphqlClient.fetch(...getGQLClientParams(...props));
-  };
-
-  const request: ApiClientRequest = (...props) => {
-    return graphqlClient.request(...getGQLClientParams(...props));
-  };
-
   const client: StorefrontApiClient = {
     config,
     getHeaders,
     getApiUrl,
-    fetch,
-    request,
+    fetch: (...props) => {
+      return graphqlClient.fetch(...getGQLClientParams(...props));
+    },
+    request: (...props) => {
+      return graphqlClient.request(...getGQLClientParams(...props));
+    },
   };
 
   return Object.freeze(client);

packages/storefront-api-client/src/types.ts

@@ -29,4 +29,15 @@ export type StorefrontApiClientOptions = Omit<
   logger?: ApiClientLogger<StorefrontApiClientLogContentTypes>;
 };
 
-export type StorefrontApiClient = ApiClient<StorefrontApiClientConfig>;
+export interface StorefrontQueries {
+  [key: string]: { variables: any; return: any };
+}
+export interface StorefrontMutations {
+  [key: string]: { variables: any; return: any };
+}
+export type StorefrontOperations = StorefrontQueries & StorefrontMutations;
+
+export type StorefrontApiClient = ApiClient<
+  StorefrontApiClientConfig,
+  StorefrontOperations
+>;