@vumotions/shopify-gql

Pre-generated Shopify GraphQL types, common queries, and codegen CLI. One install — Admin, Storefront, and Customer APIs ready to go.

Features

• Pre-generated types — 67K+ Admin types, Storefront & Customer types shipped and ready
• Common queries & mutations — import and use with full type safety, no codegen needed
• Bundled schemas — all 3 APIs (Admin, Storefront, Customer) work offline, no API key needed
• Interactive CLI — npx @vumotions/shopify-gql init scaffolds config with API selection
• createConfig() helper — per-API documents, lean mode, version overrides
• Module augmentation — client.request() returns typed results automatically

Install

npm install @vumotions/shopify-gql

Requires graphql as peer dependency — most Shopify projects already have it installed.

Quick Start

Use shipped queries

// Admin API
import { PRODUCTS_QUERY, PRODUCT_BY_ID_QUERY } from '@vumotions/shopify-gql/queries/admin'
import { PRODUCT_CREATE_MUTATION } from '@vumotions/shopify-gql/mutations/admin'

const { data } = await admin.request(PRODUCTS_QUERY, { variables: { first: 10 } })
console.log(data.products.edges) // fully typed

// Storefront API
import { STOREFRONT_PRODUCTS_QUERY } from '@vumotions/shopify-gql/queries/storefront'

const { data } = await storefront.request(STOREFRONT_PRODUCTS_QUERY, { variables: { first: 10 } })

Use operation types

import type { ShopInfoQuery, ProductsQuery } from '@vumotions/shopify-gql/types/admin'
import type { StorefrontProductsQuery } from '@vumotions/shopify-gql/types/storefront'
import type { CustomerInfoQuery } from '@vumotions/shopify-gql/types/customer'

Shipped queries & mutations

Admin Queries — @vumotions/shopify-gql/queries/admin

| Export | Description | |--------|-------------| | SHOP_INFO_QUERY | Shop name, email, plan | | PRODUCTS_QUERY | Paginated product list | | PRODUCT_BY_ID_QUERY | Full product with variants & images | | PRODUCT_BY_HANDLE_QUERY | Product by handle | | ORDERS_QUERY | Paginated order list with line items | | ORDER_BY_ID_QUERY | Full order with addresses & fulfillments | | COLLECTIONS_QUERY | Paginated collection list | | COLLECTION_BY_ID_QUERY | Collection with products | | CUSTOMERS_QUERY | Paginated customer list | | CUSTOMER_BY_ID_QUERY | Full customer with addresses |

Admin Mutations — @vumotions/shopify-gql/mutations/admin

| Export | Description | |--------|-------------| | PRODUCT_CREATE_MUTATION | Create product with media | | PRODUCT_UPDATE_MUTATION | Update product | | PRODUCT_DELETE_MUTATION | Delete product | | ORDER_UPDATE_MUTATION | Update order tags/notes | | ORDER_CANCEL_MUTATION | Cancel order with refund/restock |

Storefront Queries — @vumotions/shopify-gql/queries/storefront

| Export | Description | |--------|-------------| | STOREFRONT_SHOP_QUERY | Shop name, description, brand | | STOREFRONT_PRODUCTS_QUERY | Product list with variants | | STOREFRONT_PRODUCT_BY_HANDLE_QUERY | Full product by handle | | STOREFRONT_COLLECTIONS_QUERY | Collection list | | STOREFRONT_COLLECTION_BY_HANDLE_QUERY | Collection with products |

Customer Queries — @vumotions/shopify-gql/queries/customer

| Export | Description | |--------|-------------| | CUSTOMER_INFO_QUERY | Customer name & email |

Write custom queries

npx @vumotions/shopify-gql init      # interactive setup — choose APIs
npx @vumotions/shopify-gql codegen   # generates types for your queries

// src/shopify/admin/queries/product-queries.ts
export const GET_PRODUCTS = `#graphql
  query GetProducts {
    products(first: 10) {
      edges { node { title handle } }
    }
  }
`

Exports

| Path | Description | |------|-------------| | @vumotions/shopify-gql/queries/admin | Admin API queries | | @vumotions/shopify-gql/queries/storefront | Storefront API queries | | @vumotions/shopify-gql/queries/customer | Customer API queries | | @vumotions/shopify-gql/mutations/admin | Admin API mutations | | @vumotions/shopify-gql/mutations/storefront | Storefront API mutations | | @vumotions/shopify-gql/mutations/customer | Customer API mutations | | @vumotions/shopify-gql/types/admin | Admin operation types (query/mutation responses) | | @vumotions/shopify-gql/types/storefront | Storefront operation types | | @vumotions/shopify-gql/types/customer | Customer operation types | | @vumotions/shopify-gql/config | createConfig() helper |

createConfig(options)

Wraps @shopify/api-codegen-preset with sane defaults and bundled schemas.

import { createConfig } from '@vumotions/shopify-gql/config'

// Minimal — defaults to Admin API
export default createConfig({
  documents: ['./src/shopify/admin/**/*.ts'],
  outputDir: './src/shopify/generated'
})

// Multi-API with per-API documents
export default createConfig({
  apis: [
    { type: 'admin', documents: ['./src/shopify/admin/**/*.ts'] },
    { type: 'storefront', documents: ['./src/shopify/storefront/**/*.ts'] },
    { type: 'customer', documents: ['./src/shopify/customer/**/*.ts'] }
  ],
  outputDir: './src/shopify/generated'
})

| Option | Type | Default | Description | |--------|------|---------|-------------| | apis | string[] \| ApiConfig[] | ['admin'] | APIs to generate (each can have own documents) | | apiVersion | string | '2025-10' | Shopify API version | | documents | string[] | ['./src/**/*.ts'] | Query/mutation file globs (fallback for all APIs) | | outputDir | string | './src/generated' | Generated types output (outputDir/apiType/) | | enumsAsConst | boolean | — | Enums as const assertions | | declarations | boolean | — | Generate .d.ts files | | lean | boolean | true | Skip copying schema JSON into project | | apiKey | string | — | Fetch schema from network instead of using bundled |

CLI

npx @vumotions/shopify-gql init                     # interactive setup with API selection
npx @vumotions/shopify-gql codegen                   # auto-detect config or zero-config
npx @vumotions/shopify-gql codegen --api admin       # specify API type
npx @vumotions/shopify-gql codegen --config file.ts  # use specific config

init

Interactive setup — select which Shopify APIs you need. Generates codegen.ts with per-API document paths. If codegen.ts exists, asks before overwriting.

codegen

Generates TypeScript types for your GraphQL queries/mutations. Supports multi-API configs — runs each API project sequentially.

Recommended Folder Structure

src/shopify/
  admin/
    queries/        ← Admin API queries
    mutations/      ← Admin API mutations
  storefront/
    queries/        ← Storefront API queries
    mutations/      ← Storefront API mutations
  customer/
    queries/        ← Customer API queries
    mutations/      ← Customer API mutations
  generated/        ← codegen output (gitignore this)
    admin/
    storefront/
    customer/

How It Works

1. Base types are pre-generated from Shopify's introspection schema and shipped in the package
2. Common queries include pre-generated operation types via TypeScript module augmentation
3. Custom queries — run npx @vumotions/shopify-gql codegen to generate types locally
4. Schema JSONs are bundled for all 3 APIs — offline codegen, no API key required

License

MIT