eslint-plugin-mdx

3.7.0 verified Sat Apr 25 auth: no javascript

ESLint plugin and parser for MDX (Markdown with JSX), allowing linting of JavaScript/TypeScript syntax within MDX files. Current stable version is 3.7.0, with active maintenance and support for ESLint 10. It ships TypeScript types, supports both classic and flat ESLint configs, and can lint code blocks in MDX. Key differentiators include integration with remark-lint plugins, support for eslint-plugin-import and eslint-plugin-prettier, and a dedicated VSCode extension. Release cadence is monthly with minor and patch releases following Semantic Versioning.

Common errors

error Cannot find module 'eslint-plugin-mdx' ↓

cause Package not installed or missing from devDependencies

fix

Run npm install -D eslint-plugin-mdx or yarn add -D eslint-plugin-mdx

error ESLint: Failed to load plugin 'mdx': Cannot read properties of undefined (reading 'configs') ↓

cause Using flat config but referencing the plugin as a string instead of using plugin.flat

fix

Change config to: import plugin from 'eslint-plugin-mdx'; export default [plugin.flat];

error Parsing error: Unexpected token < in JSON at position 0 ↓

cause MDX file is being parsed as JSON or ESLint cannot find the parser

fix

Ensure 'eslint-mdx' is installed and configured as parser in your ESLint config

Warnings

breaking v3 drops CommonJS support; requires ESM-only imports ↓

fix Use import syntax instead of require(); update Node.js to >=18

breaking v3 requires ESLint >=8.0.0; does not support ESLint 7 ↓

fix Upgrade ESLint to version 8 or higher

deprecated The 'mdx/code-blocks' setting is deprecated in favor of explicit rule configuration ↓

fix Remove 'mdx/code-blocks' setting and configure code block linting via rules

gotcha Flat config requires using plugin.flat; simply listing 'eslint-plugin-mdx' in plugins array does not work ↓

fix Use `import plugin from 'eslint-plugin-mdx'; export default [plugin.flat];`

Install

npm install eslint-plugin-mdx

yarn add eslint-plugin-mdx

pnpm add eslint-plugin-mdx

Imports

eslint-plugin-mdx

wrong

const plugin = require('eslint-plugin-mdx')

correct

import plugin from 'eslint-plugin-mdx'

ESM-only since v3; default export is the plugin object.

parser
wrong
```
const parser = require('eslint-mdx').parser
```
correct
```
import { parser } from 'eslint-mdx'
```
Parser is exported from 'eslint-mdx' package, not from eslint-plugin-mdx.

rules

wrong

import rules from 'eslint-plugin-mdx/rules'

correct

import { rules } from 'eslint-plugin-mdx'

Rules object is accessible as named export from the plugin.

flat config

wrong

export default ['eslint-plugin-mdx']

correct

import plugin from 'eslint-plugin-mdx';
export default [plugin.flat]

For flat config, use plugin.flat; string references are not supported.

Quickstart

Shows both flat config (ESM) and classic config (.eslintrc) setups for linting MDX files with ESLint.

// Using flat config (ESM)
import plugin from 'eslint-plugin-mdx';
export default [
  {
    files: ['**/*.mdx'],
    ...plugin.flat,
  },
];

// Using classic config (.eslintrc)
{
  "extends": ["plugin:mdx/recommended"],
  "settings": {
    "mdx/code-blocks": true
  }
}