Announcing the Medusa ESLint Plugin: Add Guardrails to AI Agents

We are releasing Copy to clipboard@medusajs/eslint-plugin, the official ESLint plugin for Medusa projects. It codifies Medusa's conventions into static checks that run in your editor, during Copy to clipboardmedusa develop, and during Copy to clipboardmedusa build.

Why a Medusa-specific ESLint plugin

Medusa's framework has conventions that general-purpose linters don't know about. A workflow step that returns a non-serializable value, a loop inside a workflow constructor, or an API route file with the wrong name. These are all valid TypeScript that will fail at runtime.

The plugin maps these conventions to lint rules, so errors surface immediately instead of during a server restart or a production deploy.

A critical addition for AI-assisted development

AI agents writing Medusa code face a specific problem: they can produce syntactically correct TypeScript that violates Medusa's runtime conventions, and nothing in the standard toolchain will flag it before execution.

With the ESLint plugin active in the project, an agent gets structured, machine-readable feedback it can act on directly. Consider a workflow where an agent writes a step that returns a Copy to clipboardMap:

123456
// src/workflows/example.ts
export const fetchDataStep = createStep("fetch-data", async () => {
  const result = new Map([["key", "value"]])
  return new StepResponse(result) // error: @medusajs/workflow-step-non-serializable-response
})

The plugin flags this with Copy to clipboard@medusajs/workflow-step-non-serializable-response. The agent reads the error, understands the fix, and rewrites the step to return a plain, serializable object:

12345
export const fetchDataStep = createStep("fetch-data", async () => {
  const result = { key: "value" }
  return new StepResponse(result) // fixed
})

No server restart. No digging through logs. The feedback loop collapses from minutes to seconds.

What the plugin checks

The plugin ships with rules across all major Medusa extension points:

• Workflows and steps (constructor-time side effects, non-serializable responses, compensation function signatures)
• API route file naming and structure
• Module service, definition, and data model conventions
• Admin customization conventions and constraints

Rules carry one of two severities. Copy to clipboarderror rules flag violations that will break your application. Copy to clipboardwarn rules flag patterns worth reviewing. The rules reference documents each rule, its severity, and when to disable it.

Three presets for different project types

The plugin provides three presets out of the box:

• Copy to clipboardrecommended: for Medusa applications, scoped to standard directories like Copy to clipboardsrc/workflows and Copy to clipboardsrc/api. Fast, no type information required.
• Copy to clipboardstrict: extends Copy to clipboardrecommended with type-aware rules for the most thorough checking.
• Copy to clipboardmodules: for standalone module packages where source lives directly under Copy to clipboardsrc.

Get started

Projects created with Medusa v2.16.0 or later have the plugin pre-installed.

For existing projects, you can set up the plugin on any Medusa version. Refer to the ESLint plugin's documentation on how to install it.

If you're a Medusa Cloud user and you have our MCP server set up, you can use the following prompt with your AI agent to update to v2.16.0 and install the plugin:

1
Update my Medusa store to v2.16.0

Your AI agent will retrieve the necessary information from the MCP server, update your store, and set up the ESLint plugin.