@shopify/api-codegen-preset

This package enables JavaScript / TypeScript apps to use a #graphql tag to parse queries with graphql-codegen.

It produces TypeScript types for every query picked up by your codegen configuration. Shopify's clients are then able to use those types to automatically type your operation's variables and return types.

Getting started

The first step is to install the @shopify/api-codegen-preset package, using your preferred package manager:

1yarn add --dev @shopify/api-codegen-preset

1npm add --save-dev @shopify/api-codegen-preset

1pnpm add -D @shopify/api-codegen-preset

Configuration

This package provides 3 key exports, that make it increasingly easier to set up a project:

1. preset: provides the low-level implementation that converts the schema into types. Include this in a generates step.
2. shopifyApiTypes: provides all the generates steps needed for a project.
3. shopifyApiProject: one-stop-shop setup for an entire codegen project.

preset

Use this as a Codegen preset inside a generates step. This gives you complete control over your configuration if you want to set up a fully custom scenario.

Option	Type	Default	Description
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.

[!TIP] You can also set your codegen configuration to output .ts files, instead of .d.ts. That may slightly increase build sizes, but it enables you to import enums from the schema in your app code.

Example .graphqlrc.ts file

1import {ApiType, pluckConfig, preset} from '@shopify/api-codegen-preset';
2
3export default {
4  // For syntax highlighting / auto-complete when writing operations
5  schema: 'https://shopify.dev/admin-graphql-direct-proxy/2025-01',
6  documents: ['./**/*.{js,ts,jsx,tsx}'],
7  projects: {
8    default: {
9      // For type extraction
10      schema: 'https://shopify.dev/admin-graphql-direct-proxy/2025-01',
11      documents: ['./**/*.{js,ts,jsx,tsx}'],
12      extensions: {
13        codegen: {
14          // Enables support for `#graphql` tags, as well as `/* GraphQL */`
15          pluckConfig,
16          generates: {
17            './types/admin.schema.json': {
18              plugins: ['introspection'],
19              config: {minify: true},
20            },
21            './types/admin.types.d.ts': {
22              plugins: ['typescript'],
23            },
24            './types/admin.generated.d.ts': {
25              preset,
26              presetConfig: {
27                apiType: ApiType.Admin,
28              },
29            },
30          },
31        },
32      },
33    },
34  },
35};

shopifyApiTypes

This function creates the appropriate generates steps for a project. Use this function if you want to configure a custom project, or add your own generates steps.

Option	Type	Default	Description
apiType	ApiType	N/A	The API to pull schemas from.
apiVersion	string?	Oldest stable version	Pull schemas for a specific version.
apiKey	string?	N/A	The app's API key. This can be found in the app's page in Shopify Partners in the "Authentication" section. Required and only valid for the customer API preset and helpers for now
outputDir	string?	.	Where to output the types files.
documents	string[]?	./**/*.{ts,tsx}	Glob pattern for files to parse.
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.
declarations	boolean?	true	When true, create declaration (.d.ts) files with the types. When false, creates .ts files that can be imported in app code. May slightly increase build sizes.

Example .graphqlrc.ts file

1import {
2  ApiType,
3  pluckConfig,
4  shopifyApiTypes,
5} from '@shopify/api-codegen-preset';
6
7export default {
8  // For syntax highlighting / auto-complete when writing operations
9  schema: 'https://shopify.dev/admin-graphql-direct-proxy/2025-01',
10  documents: ['./app/**/*.{js,ts,jsx,tsx}'],
11  projects: {
12    // To produce variable / return types for Admin API operations
13    schema: 'https://shopify.dev/admin-graphql-direct-proxy/2025-01',
14    documents: ['./app/**/*.{js,ts,jsx,tsx}'],
15    extensions: {
16      codegen: {
17        pluckConfig,
18        generates: shopifyApiTypes({
19          apiType: ApiType.Admin,
20          apiVersion: '2025-01',
21          documents: ['./app/**/*.{js,ts,jsx,tsx}'],
22          outputDir: './app/types',
23        }),
24      },
25    },
26  },
27};

shopifyApiProject

This function creates a fully-functional project configuration.

Option	Type	Default	Description
apiType	ApiType	N/A	The API to pull schemas from.
apiVersion	string?	Oldest stable version	Pull schemas for a specific version.
outputDir	string?	.	Where to output the types files.
documents	string[]?	./**/*.{ts,tsx}	Glob pattern for files to parse.
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.
declarations	boolean?	true	When true, create declaration (.d.ts) files with the types. When false, creates .ts files that can be imported in app code. May slightly increase build sizes.

Example .graphqlrc.ts file

1import {shopifyApiProject, ApiType} from '@shopify/api-codegen-preset';
2
3export default {
4  // For syntax highlighting / auto-complete when writing operations
5  schema: 'https://shopify.dev/admin-graphql-direct-proxy/2025-01',
6  documents: ['./app/**/*.{js,ts,jsx,tsx}'],
7  projects: {
8    // To produce variable / return types for Admin API operations
9    default: shopifyApiProject({
10      apiType: ApiType.Admin,
11      apiVersion: '2025-01',
12      documents: ['./app/**/*.{js,ts,jsx,tsx}'],
13      outputDir: './app/types',
14    }),
15  },
16};

Example .graphqlrc.ts file with to generate types for UI extensions

You can specify multiple APIs in your .graphqlrc.ts file by adding multiple projects. See Generating types for multiple APIs for more information.

1import { LATEST_API_VERSION } from "@shopify/shopify-api";
2import { shopifyApiProject, ApiType } from "@shopify/api-codegen-preset";
3import type { IGraphQLConfig } from "graphql-config";
4
5function getConfig() {
6  const config: IGraphQLConfig = {
7    projects: {
8      default: shopifyApiProject({
9        apiType: ApiType.Admin,
10        apiVersion: LATEST_API_VERSION,
11        documents: ["./app/**/*.{js,ts,jsx,tsx}", "./app/.server/**/*.{js,ts,jsx,tsx}" ],
12        outputDir: "./app/types",
13      }),
14      UIExtensions: shopifyApiProject({
15        apiType: ApiType.Storefront,
16        apiVersion: LATEST_API_VERSION,
17        documents: ["./extensions/**/*.{js,ts,jsx,tsx}", "./extensions/.server/**/*.{js,ts,jsx,tsx}"],
18        outputDir: "./extensions/types",
19      }),
20    },
21  };
22
23const config = getConfig();
24export default config;

Example graphqlrc.ts file for autocompletion for Shopify Function Extensions

Enable autocompletion for Shopify Functions.

1import fs from "fs";
2import { LATEST_API_VERSION } from "@shopify/shopify-api";
3import { shopifyApiProject, ApiType } from "@shopify/api-codegen-preset";
4import type { IGraphQLConfig } from "graphql-config";
5
6function getConfig() {
7  const config: IGraphQLConfig = {
8    projects: {
9      // Generate types for your app
10      default: shopifyApiProject({
11        apiType: ApiType.Admin,
12        apiVersion: LATEST_API_VERSION,
13        documents: ["./app/**/*.{js,ts,jsx,tsx}", "./app/.server/**/*.{js,ts,jsx,tsx}"],
14        outputDir: "./app/types",
15      }),
16    },
17  };
18
19  // Enables autocompletion for your Shopify Functions
20  let extensions: string[] = [];
21  try {
22    extensions = fs.readdirSync("./extensions");
23  } catch {
24    // ignore if no extensions
25  }
26
27  for (const entry of extensions) {
28    const extensionPath = `./extensions/${entry}`;
29    const schema = `${extensionPath}/schema.graphql`;
30    if (!fs.existsSync(schema)) {
31      continue;
32    }
33    config.projects[entry] = {
34      schema,
35      documents: [`${extensionPath}/**/*.graphql`],
36    };
37  }
38
39  return config;
40}
41
42const config = getConfig();
43
44export default config;

Generating types

Once you configure your app, you can run graphql-codegen to start parsing your queries for types.

To do that, add this script to your package.json file:

1{
2  "scripts": {
3    // ...
4    "graphql-codegen": "graphql-codegen"
5  }
6}

You can then run the script using your package manager:

1yarn graphql-codegen

1npm run graphql-codegen

1pnpm graphql-codegen

Generating types for more than one API

If you have specified more than one API in your .graphqlrc.ts file, you can run the script for each API by passing the --project flag.

1npm run graphql-codegen --project=UIExtensions

1yarn graphql-codegen --project=UIExtensions

1pnpm graphql-codegen --project=UIExtensions

[!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 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:

1import '../types/admin.generated.d.ts';
2
3const response = await myGraphqlClient.graphql(
4  `#graphql
5  query getProducts($first: Int!) {
6    products(first: $first) {
7      edges {
8        node {
9          id
10          handle
11        }
12      }
13    }
14  }`,
15  {
16    variables: {
17      first: 1,
18    } as GetProductsQueryVariables,
19  },
20);
21
22const data: GetProductsQuery = response.data;

You'll note that once the script parses this query, the admin.generated.d.ts file will start including a new GetProductsQuery type that maps to your query.

You can commit these types to your repository, so that you don't have to re-run the parsing script every time.

To make your development flow faster, you can pass in the --watch flag to update the query types whenever you save a file:

1npm run graphql-codegen -- --watch

Using Generated Types with Direct API Access

With Shopify App Bridge, you can use Direct API Access to make API requests from your apps frontend directly to the Admin API.

Because you are using the Fetch API directly, the responses cannot be automatically typed. Here is how to manually type them using the automatically generated types:

1import type {  GetProductsQuery } from "app/types/admin.generated";
2
3const fetchProduct = async () => {
4  const res = await fetch('shopify:admin/api/graphql.json', {
5    method: 'POST',
6    body: JSON.stringify({
7      query: `#graphql
8        query getProducts($first: Int) {
9          products(first: $first) {
10            edges {
11              cursor
12              node {
13                title
14                handle
15              }
16            }
17          }
18        }
19      ` as const,
20      variables: { first: 1 },
21    }),
22  });
23
24  const { data } = (await res.json()) as { data: GetProductsQuery };
25  console.log(data.products.edges[0]?.node);
26};