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:

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"

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

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:

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

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

Medusa-Specific Types

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

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"

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.