From medusa-commerce
Writes modern TypeScript for Medusa v2 using DML type inference, service generics, container typing, strict mode constraints, utility types, and module patterns.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin medusa-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Fetch live docs:
site:docs.medusajs.com typescript types modules for Medusa type patternssite:www.typescriptlang.org docs handbook for latest TypeScript featuressite:docs.medusajs.com DML infer type model for DML type inferencehttps://docs.medusajs.com/learn/fundamentals/modules/service-factory for service genericssite:docs.medusajs.com container dependency injection resolve for container typingMedusa v2 projects use strict TypeScript with specific compiler options:
| Option | Value | Purpose |
|---|---|---|
strict | true | Enable all strict type checks |
target | ES2021 | Modern JS output |
module | CommonJS | Module system |
moduleResolution | node | Node.js module resolution |
esModuleInterop | true | CJS/ESM interop |
skipLibCheck | true | Skip declaration file checks |
declaration | true | Generate .d.ts files |
outDir | .medusa/server | Build output directory |
Medusa generates TypeScript types from DML model definitions. Use InferTypeOf to derive entity types without manual interface duplication:
// Fetch live docs for InferTypeOf import path
// and exact DML-to-type mapping behavior
import { InferTypeOf } from "@medusajs/framework/types"
| DML Field | Inferred TypeScript Type |
|---|---|
.text() | string |
.number() | number |
.boolean() | boolean |
.dateTime() | Date |
.json() | Record<string, unknown> |
.enum(values) | Union literal type |
.id() | string |
.hasOne(Model) | Inferred model type |
.hasMany(Model) | Array of inferred model type |
.belongsTo(Model) | Inferred model type |
.nullable() | `T |
The MedusaService factory generates a typed service class from DML models:
// Fetch live docs for MedusaService generic
// signature and generated method types
class MyService extends MedusaService({ MyModel }) {}
| Generated Method | Return Type | Purpose |
|---|---|---|
list(filters, config) | Promise<T[]> | List with filters and pagination |
retrieve(id, config) | Promise<T> | Get single entity by ID |
create(data) | Promise<T> | Create one entity |
update(data) | Promise<T> | Update entity by ID |
delete(id) | Promise<void> | Delete entity by ID |
listAndCount(filters, config) | Promise<[T[], number]> | List with total count |
softDelete(id) | Promise<T> | Soft delete entity |
restore(id) | Promise<T> | Restore soft-deleted entity |
Custom methods added to the service class are fully typed alongside generated ones.
Medusa resolves dependencies from a typed container. Module services are registered and resolved by key:
| Registration Pattern | Resolution Key | Type |
|---|---|---|
| Module service | ModuleRegistrationName.MODULE | Module service interface |
| Custom module service | Defined in module export | Custom service class |
| Remote query | ContainerRegistrationKeys.QUERY | RemoteQueryFunction |
| Logger | ContainerRegistrationKeys.LOGGER | Logger |
Access the container in API routes via req.scope.resolve("key"). In workflow steps, resolve via the StepFunction context. Use typed registration keys for compile-time safety.
| Check | Flag | Effect on Medusa Code |
|---|---|---|
strictNullChecks | Part of strict | Must handle null/undefined explicitly |
noImplicitAny | Part of strict | All parameters and variables must be typed |
strictPropertyInitialization | Part of strict | All class properties must be initialized |
noImplicitReturns | Recommended | All code paths must return a value |
noUnusedLocals | Recommended | Catch dead code early |
exactOptionalPropertyTypes | Optional | Distinguish undefined from missing |
.nullable() fields produce T | null — always check before usingretrieve() may throw if entity not found — wrap in try/catch or use list() with filters?: — provide defaults where needed| Utility Type | Use Case in Medusa |
|---|---|
Partial<T> | Update DTOs (only changed fields required) |
Required<T> | Ensure all fields present in creation |
Pick<T, Keys> | Select specific fields for API responses |
Omit<T, Keys> | Exclude internal fields from public DTOs |
Record<string, T> | Metadata and JSON fields |
NonNullable<T> | Assert non-null after null check |
Awaited<T> | Unwrap Promise return types |
ReturnType<T> | Extract return type from functions |
| Type | Import From | Purpose |
|---|---|---|
InferTypeOf | @medusajs/framework/types | Infer entity type from DML model |
MedusaRequest | @medusajs/framework/http | Typed HTTP request in API routes |
MedusaResponse | @medusajs/framework/http | Typed HTTP response in API routes |
StepResponse | @medusajs/framework/workflows-sdk | Typed workflow step return |
MedusaContainer | @medusajs/framework/types | DI container type |
Each custom module should export typed interfaces for its service:
// Fetch live docs for module type export
// conventions and service interface patterns
| File | Purpose |
|---|---|
src/modules/<name>/models/ | DML model definitions |
src/modules/<name>/service.ts | Service extending MedusaService |
src/modules/<name>/index.ts | Module definition with Module() factory |
src/modules/<name>/types.ts | Custom types and interfaces (optional) |
Pick/Omit to shape public API types from internal entity typescreate and update operationsAPI routes use Zod schemas for runtime validation. Infer TypeScript types from Zod schemas to avoid duplication:
// Fetch live docs for Zod schema usage in
// Medusa API route validators
import { z } from "zod"
| Pattern | Purpose |
|---|---|
z.infer<typeof schema> | Derive TS type from Zod schema |
defineMiddlewares | Register Zod validators on routes |
additionalDataValidator | Extend existing route validation |
InferTypeOf to derive types; never manually duplicate entity types as interfaces; keep the DML model as the single source of truthstrict: true in tsconfig.json; handle all nullable cases explicitly; use NonNullable and type guards instead of non-null assertions (!)any casts on resolved services; define explicit return types on custom service methodsz.infer; type API route handlers with MedusaRequest<T> and MedusaResponseFetch the Medusa TypeScript documentation for exact type imports, generic signatures, and DML inference patterns before implementing.