---
title: "Announcing the Medusa ESLint Plugin: Add Guardrails to AI Agents"
description: "The Medusa ESLint plugin brings Medusa-specific lint rules to your editor and CI, helping developers and AI agents catch runtime errors before they happen."
url: https://medusajs.com/blog/announcing-the-medusa-eslint-plugin-add-guardrails-to-ai-agents
last_updated: 2026-08-13T14:34:08Z
---

# Announcing the Medusa ESLint Plugin: Add Guardrails to AI Agents

_Published 2026-06-18 by Shahed  Nasser in Product_

We are releasing `@medusajs/eslint-plugin`, the official ESLint plugin for Medusa projects. It codifies Medusa's conventions into static checks that run in your editor, during `medusa develop`, and during `medusa 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 `Map`:

```ts
// 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 `@medusajs/workflow-step-non-serializable-response`. The agent reads the error, understands the fix, and rewrites the step to return a plain, serializable object:

```ts
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. `error` rules flag violations that will break your application. `warn` rules flag patterns worth reviewing. The [rules reference](https://docs.medusajs.com/resources/lint/rules) 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:

- `recommended:` for Medusa applications, scoped to standard directories like `src/workflows` and `src/api`. Fast, no type information required.
- `strict:` extends `recommended` with type-aware rules for the most thorough checking.
- `modules:` for standalone module packages where source lives directly under `src`.

## 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](https://docs.medusajs.com/resources/lint) 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:

```
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.