node-backend

Node.js Backend Patterns for Medusa v2

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com api routes middlewares express for middleware configuration
2. Web-search site:mikro-orm.io docs for MikroORM entity and query patterns
3. Web-search site:docs.medusajs.com error handling MedusaError for error types
4. Fetch https://docs.medusajs.com/learn/fundamentals/api-routes for API route conventions
5. Web-search site:node.org docs async_hooks performance for Node.js async best practices

Express Middleware Chain

Medusa Request Lifecycle

Medusa v2 is built on Express. Every HTTP request flows through a defined middleware chain:

Incoming Request
├── 1. CORS middleware
├── 2. Body parser (JSON)
├── 3. Cookie parser / session
├── 4. Authentication middleware
├── 5. Custom middlewares (middlewares.ts)
├── 6. Route handler (route.ts)
└── 7. Error handler

Custom Middleware Registration

Define custom middleware in src/api/middlewares.ts:

// Fetch live docs for defineMiddlewares
// and MiddlewareRoute type signatures
import { defineMiddlewares } from "@medusajs/medusa"

Middleware Property	Purpose
matcher	Route pattern to match (glob or regex)
method	HTTP method filter (GET, POST, etc.)
middlewares	Array of Express middleware functions
bodyParser	Configure or disable body parsing
authenticate	Apply auth requirements

Middleware Execution Order

Middleware executes in the order defined in the routes array. Global middleware (matcher *) runs before route-specific middleware.

MikroORM Entity Patterns

DML Abstraction Layer

Medusa v2 abstracts MikroORM behind DML. However, understanding the underlying ORM helps with advanced queries:

DML Layer	MikroORM Layer	Purpose
model.define()	@Entity() decorator	Define database entity
DML fields	@Property() decorators	Column definitions
DML relationships	@OneToMany(), @ManyToOne()	Relationship mappings
DML .index()	@Index() decorator	Database indexes
Generated migrations	MikroORM migration files	Schema changes

Query Patterns via Service Methods

Module services generated by MedusaService provide typed query methods:

Operation	Service Method	Underlying ORM Action
Find many	list(filters, config)	em.find() with criteria
Find one	retrieve(id, config)	em.findOneOrFail()
Create	create(data)	em.create() + em.persist()
Update	update(data)	em.assign() + em.flush()
Delete	delete(id)	em.removeAndFlush()
Soft delete	softDelete(id)	Set deleted_at timestamp

MikroORM uses the Unit of Work pattern — changes are tracked and flushed together per request.

PostgreSQL Connection Pooling

Default Connection Settings

Medusa uses MikroORM's built-in PostgreSQL driver with connection pooling:

Setting	Default	Production Recommendation
Pool minimum	2	5-10
Pool maximum	10	20-50 (based on load)
Idle timeout	30s	10-30s
Connection timeout	5s	5-10s
SSL mode	Disabled	require or verify-full

Pool Management

• Configure via DATABASE_URL query parameters or medusa-config.ts database options
• Track active vs idle connections via PostgreSQL's pg_stat_activity
• Set pool max below PostgreSQL max_connections (reserve for admin)
• Use PgBouncer for external pooling in high-concurrency scenarios

Async Patterns

Async/Await Best Practices

Pattern	Use Case	Avoid
async/await	Sequential async operations	Callback-based patterns
Promise.all()	Parallel independent operations	Sequential awaits for independent tasks
Promise.allSettled()	Parallel ops where some may fail	Promise.all() when partial success is OK
for await...of	Async iterators, streams	Manual iterator consumption
try/catch in async	Error handling in async functions	Unhandled promise rejections

Medusa Workflow Steps

Workflow steps are inherently async. Each step receives context and returns a StepResponse:

// Fetch live docs for createStep async
// signature and StepResponse typing

Event-Driven Async (Subscribers)

Subscribers handle events asynchronously. They execute in the worker process when running in separate mode:

Concept	Implementation
Event emission	Automatic on entity changes or manual via event bus
Subscriber registration	Export config with event and handler function
Execution context	Runs in worker process (async from request)
Error handling	Subscriber errors do not affect the triggering request

Error Handling

Medusa Error Types

Error Class	HTTP Status	Use Case
MedusaError	Varies	Base error class with type codes
NOT_FOUND	404	Entity not found
INVALID_DATA	400	Validation failure
UNAUTHORIZED	401	Authentication required
NOT_ALLOWED	403	Insufficient permissions
CONFLICT	409	Duplicate or conflicting state
UNEXPECTED_STATE	500	Internal logic error

Error Handling in API Routes

// Fetch live docs for MedusaError import
// and error type enum values
import { MedusaError } from "@medusajs/framework/utils"

Error Handling Strategy

• Throw MedusaError with appropriate type in service methods
• Medusa's error handler middleware converts errors to HTTP responses
• Never swallow errors silently — log and re-throw or handle explicitly
• Use try/catch in workflow steps and return compensation data on failure

Logging

Built-in Logger

Medusa provides a structured logger accessible via the DI container:

Log Level	Method	Use Case
error	logger.error()	Unrecoverable errors, exceptions
warn	logger.warn()	Degraded state, deprecated usage
info	logger.info()	Significant events, startup, shutdown
debug	logger.debug()	Detailed diagnostic information

Resolve the logger from the container via container.resolve("logger"). Log at appropriate levels, include contextual data (entity IDs, operation names), and configure structured JSON output in production.

Node.js Runtime Considerations

Concern	Recommendation
Node.js version	Use Node.js 20+ (LTS) for Medusa v2
Memory	Set --max-old-space-size for large catalogs
Event loop	Avoid blocking the event loop with synchronous operations
Graceful shutdown	Handle SIGTERM to close connections and finish in-flight requests
Clustering	Use multiple server instances (not Node cluster) behind a load balancer

Best Practices

• Middleware discipline — define all custom middleware in src/api/middlewares.ts; order middleware from general to specific; use route matchers to scope middleware narrowly
• Database access — always go through module services, never access the entity manager directly; use list with filters instead of raw queries; leverage soft deletes for data preservation
• Async safety — always await async operations; use Promise.all for parallel independent work; handle errors in every try/catch block with meaningful error types
• Performance — configure connection pool size for expected concurrency; use Redis for caching frequently accessed data; avoid N+1 queries by using service config.relations to eager-load relationships

Fetch the Medusa API route and middleware documentation for exact handler signatures, error types, and logging configuration before implementing.