@doswiftly/storefront-operations

Pre-built GraphQL operations and schema for DoSwiftly e-commerce storefronts. Contains the GraphQL schema file, ready-to-use queries, mutations, and fragments for products, collections, cart, checkout, and customer management.

No running backend needed for codegen — the schema is included as a file.

Installation

npm install @doswiftly/storefront-operations
# or
pnpm add @doswiftly/storefront-operations

Quick Start

1. Install dependencies

npm install @doswiftly/storefront-operations @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node

2. Create codegen.ts

import { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  // Schema from package — no running backend needed!
  schema: "node_modules/@doswiftly/storefront-operations/schema.graphql",
  documents: [
    "node_modules/@doswiftly/storefront-operations/**/*.graphql",
    "src/**/*.{ts,tsx}", // Your custom operations (optional)
  ],
  generates: {
    "src/generated/graphql.ts": {
      plugins: ["typescript", "typescript-operations", "typed-document-node"],
    },
  },
};

export default config;

3. Add script to package.json

{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.ts"
  }
}

4. Run codegen

npm run codegen

5. Use in your components

import { useQuery } from '@tanstack/react-query';
import { graphqlClient } from '@/lib/graphql-client';
import { ProductsDocument } from '@/generated/graphql';

export function ProductList() {
  const { data, isLoading } = useQuery({
    queryKey: ['products'],
    queryFn: () => graphqlClient.request(ProductsDocument, { first: 12 }),
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div className="grid grid-cols-3 gap-4">
      {data?.products.edges.map(({ node }) => (
        <ProductCard key={node.id} product={node} />
      ))}
    </div>
  );
}

Available Operations

Queries

| Operation | Description | | ------------------- | ---------------------------------------- | | Shop | Shop configuration, currencies, settings | | Product | Single product by ID or handle | | Products | Product list with pagination and filters | | ProductSearch | Full-text product search | | Collection | Collection with its products | | Collections | All collections | | Category | Category with hierarchy | | Categories | Category tree | | Cart | Cart contents by ID | | Customer | Logged-in customer data | | CustomerOrders | Customer order history | | CustomerAddresses | Customer saved addresses |

Mutations

Cart

• CartCreate - Create a new cart
• CartLinesAdd - Add items to cart
• CartLinesUpdate - Update item quantities
• CartLinesRemove - Remove items from cart
• CartDiscountCodesUpdate - Apply/remove discount codes
• CartBuyerIdentityUpdate - Set customer info on cart
• CartNoteUpdate - Add note to cart

Authentication

• CustomerCreate - Register new customer
• CustomerLogin - Login and get token
• CustomerLogout - Logout
• CustomerTokenRenew - Refresh auth token

Customer Profile

• CustomerUpdate - Update profile info
• CustomerAddressCreate - Add new address
• CustomerAddressUpdate - Update address
• CustomerAddressDelete - Delete address
• CustomerDefaultAddressUpdate - Set default address

Password

• CustomerPasswordRecover - Request password reset email
• CustomerPasswordReset - Reset password with token

Schema

The package includes schema.graphql — the full GraphQL schema auto-generated from the backend (NestJS code-first). This enables offline codegen without a running backend.

To update the schema after backend changes:

# From monorepo root (requires backend to have been started at least once)
cd packages/@doswiftly/storefront-operations
pnpm run sync

TypeScript Support

All operations are fully typed. After running codegen, you get:

• Document nodes for each operation
• Input types for variables
• Response types for results

import {
  ProductDocument,
  ProductQuery,
  ProductQueryVariables,
} from "@/generated/graphql";

// Full type safety
const variables: ProductQueryVariables = {
  handle: "awesome-product",
};

Custom Operations

You can add your own GraphQL operations alongside the package operations:

# src/graphql/custom-queries.graphql
query FeaturedProducts {
  products(first: 4, filters: { tag: "featured" }) {
    edges {
      node {
        ...ProductCard
      }
    }
  }
}

Re-run npm run codegen to generate types for your custom operations.

Links

• DoSwiftly Website
• DoSwiftly Documentation
• GraphQL API Reference

License

MIT