ts-modern

Modern TypeScript for Medusa v2

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com typescript types modules for Medusa type patterns
2. Web-search site:www.typescriptlang.org docs handbook for latest TypeScript features
3. Web-search site:docs.medusajs.com DML infer type model for DML type inference
4. Fetch https://docs.medusajs.com/learn/fundamentals/modules/service-factory for service generics
5. Web-search site:docs.medusajs.com container dependency injection resolve for container typing

TypeScript Configuration in Medusa

Medusa 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

DML Type Inference

InferTypeOf Pattern

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

Service Generics

MedusaService Factory

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 Signatures

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.

Container Typing

Dependency Injection Container

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

Typing the Container in Routes and Workflows

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.

Strict Mode Constraints

Key Strict Checks

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

Handling Nullable Types in Medusa

• DML .nullable() fields produce T | null — always check before using
• retrieve() may throw if entity not found — wrap in try/catch or use list() with filters
• Optional config parameters use ?: — provide defaults where needed

Utility Types for Medusa

Commonly Used TypeScript Utilities

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

Medusa-Specific Types

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

Module Interface Patterns

Defining Module Types

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)

Generic Constraints on Module Boundaries

• Module services should accept and return typed DTOs, not raw entities
• Use Pick/Omit to shape public API types from internal entity types
• Define explicit input types for create and update operations

Zod Validators and Type Inference

API 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

Best Practices

• DML-first typing — define models in DML and use InferTypeOf to derive types; never manually duplicate entity types as interfaces; keep the DML model as the single source of truth
• Strict mode always — enable strict: true in tsconfig.json; handle all nullable cases explicitly; use NonNullable and type guards instead of non-null assertions (!)
• Container type safety — use typed registration keys when resolving from the container; avoid any casts on resolved services; define explicit return types on custom service methods
• API type flow — define Zod schemas for request validation; infer TypeScript types from Zod with z.infer; type API route handlers with MedusaRequest<T> and MedusaResponse

Fetch the Medusa TypeScript documentation for exact type imports, generic signatures, and DML inference patterns before implementing.