Adding Entity Types

Overview

Implement new Saleor entity types following a 7-step pipeline: schema, GraphQL operations, repository, bulk mutations, service, tests, and deployment stage. Each step builds on the previous, producing a complete entity module.

When to Use

• Implementing a new Saleor entity (e.g., categories, products, menus)
• Adding a new module to src/modules/
• Creating features that need full CRUD with the Saleor API
• Not for: Modifying existing entities (see understanding-saleor-domain)

Quick Reference

E2E Workflow

+-----------------+
| 1. Zod Schema   |  Define validation + infer types
+--------+--------+
         v
+-----------------+
| 2. GraphQL Ops  |  gql.tada queries/mutations
+--------+--------+
         v
+-----------------+
| 3. Repository   |  Data access + error wrapping
+--------+--------+
         v
+-----------------+
| 4. Bulk Mutations|  Chunking + error policies
+--------+--------+
         v
+-----------------+
| 5. Service      |  Business logic + orchestration
+--------+--------+
         v
+-----------------+
| 6. Tests        |  Unit + integration + builders
+--------+--------+
         v
+-----------------+
| 7. Pipeline     |  Add deployment stage
+-----------------+

Step-by-Step Implementation

Step 1: Define Zod Schema

Create in src/modules/config/schema/<entity>.schema.ts. Key patterns:

• Infer types with z.infer<typeof schema> (never manual type definitions)
• Use branded types for slugs/names (e.g., transform((v) => v as EntitySlug))
• Use discriminated unions for variant types

See references/zod-schemas.md for detailed patterns.

Step 2: Create GraphQL Operations

Define in src/modules/<entity>/operations.ts. Key patterns:

• Import graphql from @/lib/graphql/graphql (gql.tada auto-types)
• Use ResultOf<typeof Query> for type inference
• Always include errors { field, message, code } in mutations
• Follow naming: get<Entity>Query, create<Entity>Mutation, bulk<Action><Entity>Mutation

See references/graphql-operations.md for detailed patterns.

Step 3: Implement Repository

Create src/modules/<entity>/repository.ts. Key patterns:

• Define interface (e.g., EntityOperations) for testability
• Wrap errors with GraphQLError.fromCombinedError()
• Always check both result.error and result.data?.mutation?.errors

See references/repository-service.md for detailed patterns.

Step 4: Add Bulk Mutations

Integrate chunked processing in repository. Key patterns:

• Use processInChunks from @/lib/utils/chunked-processor
• Threshold: BulkOperationThresholds.DEFAULT (10 items)
• Chunk size: ChunkSizeConfig.DEFAULT_CHUNK_SIZE (10 items/chunk)
• Error policy: IGNORE_FAILED (continue processing, report all failures)

See references/bulk-mutations.md for detailed patterns.

Step 5: Create Service Layer

Create src/modules/<entity>/service.ts. Key patterns:

• Inject repository via constructor (interface, not concrete class)
• Validate inputs with Zod schema before passing to repository
• Orchestrate bulk operations and collect results

See references/repository-service.md for detailed patterns.

Step 6: Write Tests

Create in src/modules/<entity>/. Key patterns:

• Use test builders with fluent interface (entityBuilder().withName("Test").build())
• Mock repositories with vi.fn() for unit tests
• Use MSW for integration tests with real GraphQL operations
• Validate builder output with Zod schema in build()

See references/testing.md for detailed patterns.

Step 7: Add to Deployment Pipeline

Create stage in src/modules/deployment/stages/<entity>-stage.ts:

• Set order after dependencies (entities this depends on)
• Skip if no config entries: if (!config.entities?.length) return { skipped: true }
• Delegate to service layer

Validation Checkpoints

Common Mistakes

Architecture Decision Summary

Troubleshooting

Schema Won't Compile

GraphQL Errors

Deployment Stage Failures

Rollback

If a deployment stage fails mid-execution:

1. Run pnpm dev introspect to capture the current (partially modified) state
2. Compare with git history to identify what changed
3. Manually fix or re-deploy with corrected config

Related Skills

• Domain concepts: See understanding-saleor-domain
• Testing details: See analyzing-test-coverage
• Zod patterns: See designing-zod-schemas
• GraphQL details: See writing-graphql-operations
• Code quality: See reviewing-typescript-code