{"id":13140,"library":"eslint-mdx","title":"ESLint Parser and Plugin for MDX","description":"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).","status":"active","version":"3.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/mdx-js/eslint-mdx","tags":["javascript","eslint","eslint-mdx","eslint-parser","eslint-parser-mdx","mdx","typescript"],"install":[{"cmd":"npm install eslint-mdx","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-mdx","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-mdx","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core peer dependency for ESLint functionality.","package":"eslint","optional":false},{"reason":"Peer dependency required for integrating remark-lint rules for markdown syntax.","package":"remark-lint-file-extension","optional":true}],"imports":[{"note":"For modern flat ESLint configurations (eslint.config.js), import the plugin directly. `eslint-plugin-mdx` bundles the parser.","wrong":"const mdx = require('eslint-plugin-mdx');","symbol":"mdx","correct":"import mdx from 'eslint-plugin-mdx';"},{"note":"Type imports for parser options are typically from the `eslint-mdx` package's internal types path.","wrong":"import { ParserOptions } from 'eslint-mdx';","symbol":"Parser","correct":"import type { ParserOptions } from 'eslint-mdx/lib/types';"},{"note":"For classic ESLint configurations (.eslintrc.js), reference the parser by its package name string, not by direct import.","wrong":"parser: require('eslint-mdx')","symbol":"No direct import for classic config","correct":"parser: 'eslint-mdx'"}],"quickstart":{"code":"/* eslint.config.js */\nimport mdx from 'eslint-plugin-mdx';\n\nexport default [\n  {\n    files: ['**/*.mdx'],\n    parser: mdx.parser,\n    plugins: {\n      mdx: mdx\n    },\n    rules: {\n      // Example MDX-specific rules\n      'mdx/no-unused-expressions': 'error',\n      'mdx/no-jsx-as-expression': 'warn',\n      // Enable markdown linting via remark-lint rules\n      'mdx/remark': ['error', {\n        // Example remark-lint rule\n        'remark-lint-heading-style': 'atx'\n      }]\n    },\n    settings: {\n      'mdx/code-blocks': true, // Enable linting for code blocks within MDX\n      'mdx/prettier': true // Integrate with Prettier\n    }\n  },\n  // General JavaScript/TypeScript rules for code within MDX\n  {\n    files: ['**/*.mdx/**/*.js', '**/*.mdx/**/*.jsx', '**/*.mdx/**/*.ts', '**/*.mdx/**/*.tsx'],\n    extends: [\n      // For example, extend a base JavaScript/TypeScript config\n      'eslint:recommended'\n    ],\n    parserOptions: {\n      ecmaVersion: 'latest',\n      sourceType: 'module',\n      ecmaFeatures: {\n        jsx: true\n      }\n    }\n  }\n];","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.5.0"},{"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.","message":"ESLint 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.","severity":"gotcha","affected_versions":">=3.6.2"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=3.7.0"},{"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' }]`.","message":"`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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"The `eslint-mdx` parser package is not installed or incorrectly referenced in the ESLint configuration.","error":"ESLint couldn't find the parser \"eslint-mdx\" loaded from the configuration file"},{"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 }`).","cause":"The `eslint-plugin-mdx` package is not installed or incorrectly referenced in the ESLint configuration.","error":"ESLint couldn't find the plugin \"mdx\" loaded from the configuration file"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'body') at getAST"},{"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.","cause":"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'.","error":"Parsing error: The keyword 'await' is reserved (ESLint)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}