How shopify/shopify-api-js works
Project type and purpose
• This is an open-source monorepo containing several JavaScript/TypeScript libraries and utilities for building Shopify apps.
• It is *not* a single end-user application but a suite of API client libraries (@shopify/shopify-api, @shopify/storefront-api-client, @shopify/admin-api-client, @shopify/graphql-client) plus a GraphQL codegen preset (@shopify/api-codegen-preset).
File structure
• Top‐level configurations: turbo.json, tsconfig*.json, .github/workflows/*, package.json – orchestrate builds, tests, and releases.
• packages/: each subfolder is an independently built, tested, and published npm package.
• Within each package:
• src/ holds the source modules (e.g. auth/, clients/, graphql-client/, rest/, adapters/).
• tests/ or __tests__/ contain Jest test suites.
• Build configs (babel.config.json, rollup.config.*, tsconfig.*.json).
• packages/shopify-api/adapters/: adapter pattern for different runtimes (Node, Cloudflare Worker, mock, web).
README for insights
• Describes the purpose of each package.
• Emphasizes server use (@shopify/shopify-api, @shopify/admin-api-client) vs. client/server flexibility (@shopify/storefront-api-client) vs. generic GraphQL client (@shopify/graphql-client) vs. codegen (@shopify/api-codegen-preset).
Main components
a. Monorepo infrastructure
• Turbo build orchestrator
• GitHub Actions CI/CD pipelines (lint, test, release)
b. Packages (modules)
• shopify-api: OAuth, Admin API (REST/GraphQL), webhooks, billing, session management
• admin-api-client: REST & GraphQL Admin API wrapper
• storefront-api-client: GraphQL Storefront API wrapper
• graphql-client: generic GraphQL client utilities
• api-codegen-preset: GraphQL codegen plugin
c. Adapters (inside shopify-api)
• Node, Cloudflare Worker, web-api, mock – abstracting HTTP transport and environment
d. Build & Test Tools
• Babel + Rollup pipelines
• TypeScript compilation
• Jest test runner
e. External Services
• Shopify Admin API endpoints (REST/GraphQL)
• Shopify Storefront API (GraphQL)
• npm registry (for package publishing)
Relationships and data flows
• Developer workflow:
Developer → Monorepo root → selects/edits package → build/test → publishes to npm
• Runtime flow:
Application code → calls library (e.g. @shopify/shopify-api or @shopify/storefront-api-client) → adapter → HTTP request → Shopify API → JSON/GraphQL response → library parses → returns to application
• Codegen flow:
Source #graphql tags → processed by api-codegen-preset in build pipeline → generates typed documents consumed by GraphQL clients
Architectural patterns and design principles
• Monorepo + modular packages: independent versioning, clear boundaries
• Adapter pattern for environment-specific HTTP transport
• Separation of concerns: auth, client operations, validations, codegen
• Type safety via TypeScript and generated GraphQL types