eslint-mdx

library3.7.0jsnpmunverified

eslint-mdx provides an ESLint parser and plugin for MDX files, enabling comprehensive linting of both embedded JavaScript/TypeScript code and markdown syntax. It integrates with `remark-lint` to apply markdown-specific rules, differentiating it from parsers that only handle code blocks. The package is currently stable at version `3.7.0` and is actively maintained with frequent minor and patch releases, ensuring compatibility with the latest ESLint versions, including ESLint 10. It supports both classic (`.eslintrc.*`) and modern flat (`eslint.config.js`) ESLint configurations, offering flexibility for various project setups. The project is a monorepo, publishing both `eslint-mdx` (the parser) and `eslint-plugin-mdx` (the plugin and recommended configurations).

testing

npm install eslint-mdx

github ↗package ↗

INSTALL

IMPORT

SIG · ESLINT-MDX

eslint-mdx

testingjavascriptv3.7.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mdx

✓ import mdx from 'eslint-plugin-mdx';

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

For modern flat ESLint configurations (eslint.config.js), import the plugin directly. `eslint-plugin-mdx` bundles the parser.

Parser

✓ import type { ParserOptions } from 'eslint-mdx/lib/types';

✗ import { ParserOptions } from 'eslint-mdx';

Type imports for parser options are typically from the `eslint-mdx` package's internal types path.

No direct import for classic config

✓ parser: 'eslint-mdx'

✗ parser: require('eslint-mdx')

For classic ESLint configurations (.eslintrc.js), reference the parser by its package name string, not by direct import.

This quickstart demonstrates how to set up `eslint-plugin-mdx` using ESLint's flat configuration (`eslint.config.js`). It shows how to apply MDX-specific rules, enable linting of code blocks, and integrate with `remark-lint` for markdown syntax checking. It also includes a basic configuration for linting the embedded JavaScript/TypeScript code within MDX files.

/* eslint.config.js */ import mdx from 'eslint-plugin-mdx'; export default [ { files: ['**/*.mdx'], parser: mdx.parser, plugins: { mdx: mdx }, rules: { // Example MDX-specific rules 'mdx/no-unused-expressions': 'error', 'mdx/no-jsx-as-expression': 'warn', // Enable markdown linting via remark-lint rules 'mdx/remark': ['error', { // Example remark-lint rule 'remark-lint-heading-style': 'atx' }] }, settings: { 'mdx/code-blocks': true, // Enable linting for code blocks within MDX 'mdx/prettier': true // Integrate with Prettier } }, // General JavaScript/TypeScript rules for code within MDX { files: ['**/*.mdx/**/*.js', '**/*.mdx/**/*.jsx', '**/*.mdx/**/*.ts', '**/*.mdx/**/*.tsx'], extends: [ // For example, extend a base JavaScript/TypeScript config 'eslint:recommended' ], parserOptions: { ecmaVersion: 'latest', sourceType: 'module', ecmaFeatures: { jsx: true } } } ];

Debug

Known issues

breakingVersion 3.5.0 refactored to target `ES2022` and dropped the `tslib` dependency. Projects using older JavaScript environments or relying on specific `tslib` functionality might encounter issues.

fix

Ensure your project's Node.js environment supports ES2022 features (Node.js >=18.0.0 is the engine requirement). Update TypeScript and build configurations if necessary.

affects: >=3.5.0

gotchaESLint introduced a new flat configuration system (`eslint.config.js`) in version 9. While `eslint-mdx` supports both classic and flat configs, migrating existing `.eslintrc.*` setups to the new flat config requires understanding the new module-based configuration approach.

fix

Refer to the `eslint-mdx` documentation and ESLint's official migration guide for adapting your configuration. Use `import mdx from 'eslint-plugin-mdx'` for flat configs, and ensure the `parser` and `plugins` are correctly defined within the configuration objects.

affects: >=3.6.2

breakingThe `eslint-plugin-mdx` package added support for `eslint` 10 in version `3.7.0`. While this primarily adds compatibility, it's essential to ensure your `eslint` peer dependency matches the `>=8.0.0` requirement and to be aware of any ESLint 10-specific breaking changes that might affect your overall linting setup.

fix

Upgrade your `eslint` dependency to a compatible version (>=8.0.0) and review ESLint's release notes for version 10 for any global configuration adjustments.

affects: >=3.7.0

gotcha`eslint-mdx` uses `remark-lint` plugins for markdown linting. To enable this, you must explicitly configure the `mdx/remark` rule and provide the desired `remark-lint` rules within its options. Without this, only the JavaScript/TypeScript parts of MDX will be linted.

fix

Add the `mdx/remark` rule to your ESLint configuration and specify an array of `remark-lint` rules, for example: `'mdx/remark': ['error', { 'remark-lint-heading-style': 'atx' }]`.

affects: >=3.0.0

Errors

Common errors & fixes

ESLint couldn't find the parser "eslint-mdx" loaded from the configuration file

The `eslint-mdx` parser package is not installed or incorrectly referenced in the ESLint configuration.

fix

Ensure `eslint-mdx` is installed (`npm install --save-dev eslint-mdx` or `yarn add -D eslint-mdx`) and correctly specified in your `.eslintrc.*` or `eslint.config.js` file (e.g., `parser: 'eslint-mdx'` for classic config, or `parser: mdx.parser` for flat config).

ESLint couldn't find the plugin "mdx" loaded from the configuration file

The `eslint-plugin-mdx` package is not installed or incorrectly referenced in the ESLint configuration.

fix

Install `eslint-plugin-mdx` (`npm install --save-dev eslint-plugin-mdx`) and ensure it's listed in your `plugins` array (`plugins: ['mdx']` for classic) or imported and passed to the `plugins` object for flat config (`plugins: { mdx }`).

TypeError: Cannot read properties of undefined (reading 'body') at getAST

This often occurs when `eslint-mdx` attempts to parse an MDX file that is syntactically invalid or malformed, leading to an incomplete or unexpected AST structure from the underlying MDX parser.

fix

Check the MDX file for syntax errors, unclosed tags, or malformed JSX/markdown elements. Ensure all components are correctly imported or defined within the MDX context.

Parsing error: The keyword 'await' is reserved (ESLint)

The `parserOptions.ecmaVersion` in your ESLint configuration is too low for the JavaScript syntax being used within your MDX files, or `sourceType` is not set to 'module'.

fix

Update `parserOptions.ecmaVersion` to 'latest' or at least '2022' and set `parserOptions.sourceType: 'module'` in your ESLint configuration for the MDX files or embedded JavaScript blocks.

Upgrade

Version history

3.7.0latest on npm

Audit

Dependencies

eslintrequiredCore peer dependency for ESLint functionality.

remark-lint-file-extensionoptionalPeer dependency required for integrating remark-lint rules for markdown syntax.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/mdx-js/eslint-mdx ↗

packagehttps://www.npmjs.com/package/eslint-mdx ↗