Medusa ESLint Plugin

In this section of the documentation, you'll learn how to set up and use the Medusa ESLint plugin in your application.

The Medusa ESLint plugin (@medusajs/eslint-plugin) is the official ESLint plugin for Medusa projects. It codifies Medusa's conventions into static checks that run while you write code in your editor and when you build or develop your application.

The plugin is useful for both developers and AI agents working on your codebase, as it provides immediate feedback on code that violates Medusa's conventions.

The plugin catches mistakes that often lead to runtime errors or unexpected behavior, such as using loops in a workflow's constructor, returning a non-serializable value from a step, or naming an API route file incorrectly. Each rule maps to a Medusa convention.

How to Install the Plugin#

1. Installation#

To use the plugin in an existing project, install it along with ESLint and jiti:

yarn
pnpm
npm

Where:

• @medusajs/eslint-plugin is the plugin that provides Medusa's lint rules.
• eslint is a peer dependency of the plugin. The plugin supports ESLint v8.57 and later, including the flat config format introduced in v9.
• jiti allows ESLint to load a TypeScript configuration file (eslint.config.ts). Install it if you want to write your ESLint configuration in TypeScript.

2. Add an ESLint Configuration File#

a. Configuration for Monorepo Projects

After installing the plugin, create an eslint.config.ts file at the root of your monorepo that spreads one of the plugin's presets:

eslint.config.ts
1import { defineConfig } from "eslint/config"2import medusa from "@medusajs/eslint-plugin"3
4export default defineConfig([...medusa.configs.recommended])

The plugin only supports ESLint's flat config format.

Then, in the Medusa application package, create a similar eslint.config.ts file:

apps/medusa-app/eslint.config.ts
1import { defineConfig } from "eslint/config"2import medusa from "@medusajs/eslint-plugin"3
4export default defineConfig([...medusa.configs.recommended])

This setup is necessary to support both medusa lint command and code editor hints.

You can add overide rules in the application package's configuration file to customize linting, as explained in the usage guidelines.

To avoid type errors on this file, make sure to add it to apps/backend/tsconfig.json's exclude array:

apps/backend/tsconfig.json
1{2  "exclude": [3    // ...4    "eslint.config.*"5  ]6}

b. Configuration for Standalone Medusa Projects

After installing the plugin, create an eslint.config.ts file at the root of your project that spreads one of the plugin's presets:

eslint.config.ts
1import { defineConfig } from "eslint/config"2import medusa from "@medusajs/eslint-plugin"3
4export default defineConfig([...medusa.configs.recommended])

The plugin only supports ESLint's flat config format.

You can add your own configuration blocks after the preset to customize linting, as explained in the usage guidelines.

Configuration with ESLint v8.57

The plugin's presets use the flat config format, which is the default since ESLint v9. If you're using ESLint v8.57, you can still use the same eslint.config.ts file, but you must opt in to the flat config format.

The Medusa CLI lint commands load the eslint.config.ts file directly, so they work with ESLint v8.57 without any extra setup.

However, when you run the eslint command directly or use an editor integration, ESLint v8 doesn't use the flat config file by default. To enable it, set the ESLINT_USE_FLAT_CONFIG environment variable to true:

Terminal
❯ESLINT_USE_FLAT_CONFIG=true npx eslint .

3. Set Up Your IDE#

It's highly recommended to install an ESLint plugin or extension in your code editor. This way, you see the plugin's errors and warnings inline as you write code, and you can auto-fix issues during development instead of waiting for a build or a manual lint run.

For example:

• If you use VS Code, install the ESLint extension.
• If you use a JetBrains IDE such as WebStorm, enable ESLint in the IDE's settings.

To auto-fix issues whenever you save a file in VS Code, enable the following in your editor settings:

.vscode/settings.json
1{2  "editor.codeActionsOnSave": {3    "source.fixAll.eslint": "explicit"4  }5}

Presets#

The plugin provides three presets that you spread into your ESLint configuration. Choose the preset based on your package type and how thorough you want the linting to be.

recommended#

The recommended preset is the default for Medusa projects. It enables rules scoped to your project's directories, such as src/workflows and src/api. These rules don't require TypeScript type information, so they're fast to run.

Use this preset in all Medusa projects:

eslint.config.ts
1import { defineConfig } from "eslint/config"2import medusa from "@medusajs/eslint-plugin"3
4export default defineConfig([...medusa.configs.recommended])

strict#

The strict preset extends recommended with additional rules that require TypeScript type information or that check across multiple files. These rules are more thorough, but slower to run.

To use the type-aware rules, your ESLint configuration must set parserOptions.project. Use this preset when you want the most thorough checking:

eslint.config.ts
1import { defineConfig } from "eslint/config"2import medusa from "@medusajs/eslint-plugin"3
4export default defineConfig([...medusa.configs.strict])

modules#

The modules preset is meant for packages whose only purpose is to provide a module or a module provider, such as a published module package. In these packages, a module's source code lives directly under src, rather than under src/modules as it does in a Medusa application.

This preset applies only the rules that govern a module's service, module definition, and data models, scoped to the package's layout. It's zero-config and doesn't require TypeScript type information.

eslint.config.ts
1import { defineConfig } from "eslint/config"2import medusa from "@medusajs/eslint-plugin"3
4export default defineConfig([...medusa.configs.modules])

Lint your Project#

The Medusa CLI provides commands to lint your project. The commands require a flat ESLint config file (eslint.config.ts, eslint.config.js, or another supported extension). Config detection uses ESLint's own resolution, which walks ancestor directories, so a config at a monorepo root applies to nested projects.

medusa lint#

Use the medusa lint command to lint your project:

yarn
pnpm
npx

By default, the command lints the whole project. You can pass paths to lint specific files or directories:

yarn
pnpm
npx

The command accepts the following options:

• --fix: Auto-fix lint issues where possible.
• --quiet: Report lint errors only, suppressing warnings.

The command exits with a non-zero code if it finds lint errors.

Lint while Developing#

The medusa develop command lints your project once at startup, before the development server starts. If the linter finds errors, the development server doesn't start.

The command accepts the following lint options:

• --lint and --no-lint: Whether to run the linter before starting the development server. By default, linting is enabled.
• --fix and --no-fix: Auto-fix lint issues where possible before starting. By default, auto-fixing is disabled.

For example, to start the development server without linting:

Terminal
❯npx medusa develop --no-lint

Lint while Building#

The medusa build command lints your project after generating types and before building. Unlike develop, linting during build is non-blocking: lint problems are surfaced as warnings, but they never fail the build.

The command accepts the following lint options:

• --lint and --no-lint: Whether to run the linter before building. By default, linting is enabled.
• --fix and --no-fix: Auto-fix lint issues where possible before building. By default, auto-fixing is disabled.
• --quiet: Report lint errors only, suppressing warnings.

For example, to build your project without linting:

Terminal
❯npx medusa build --no-lint

Usage Guidelines#

Rule Severities#

Each rule has one of two severities:

• error: The rule flags code that heavily violates Medusa's conventions and may lead to runtime errors or unexpected results.
• warn: The rule flags code that you should review, but that won't necessarily break your application.

The severity of each rule is mentioned in its reference page.

Change a Rule's Severity or Disable it#

To change a rule's severity or disable it, add a configuration block after the preset in your Medusa application's eslint.config.ts file.

For example, to disable the admin-env-vars-import-meta rule:

eslint.config.ts
1import { defineConfig } from "eslint/config"2import medusa from "@medusajs/eslint-plugin"3
4export default defineConfig([5  ...medusa.configs.recommended,6  {7    rules: {8      "@medusajs/admin-env-vars-import-meta": "off",9    },10  },11])

You can also disable a rule for a single line using an inline comment:

Code
1// eslint-disable-next-line @medusajs/admin-env-vars-import-meta2console.log(process.env.MEDUSA_BACKEND_URL)

Or disable a rule for a whole file:

Code
1/* eslint-disable @medusajs/admin-env-vars-import-meta */2// The rest of the file's code

Don't Disable Error Rules#

Rules with the error severity flag code that heavily violates Medusa's conventions. Disabling them can lead to runtime errors or unexpected behavior in your application. If a rule's severity is error, fix the underlying issue instead of disabling the rule.

Only consider disabling rules with the warn severity, and only when you're certain the rule reports a false positive in your case. Each warning rule's reference page shows how to turn it off.

Available Rules#

Refer to the Rules reference for the full list of rules, including what each rule targets, why it's important, and its severity.