Fixing MDX linting errors in Next.js using eslint-plugin-mdx

Recently I was getting mdx Eslint linting errors in my mdx files where I write my posts. And a red squiggly line appears at the top of my mdx files where I had the starting —-- triple hyphens which indicate the start of the frontmatter data block of the file. I needed to let ESLint know of such mdx frontmatter syntax so that it would not throw a linting error, thereby resulting in a commit failure.

After a bit of research, I came across an issue on the eslint-mdx Github repository which provided the configuration I need to add to my .eslintrc.js file:

module.exports = {
	extends: [
		'eslint:recommended',
		'plugin:mdx/recommended',
		'plugin:prettier/recommended',
		'next',
		'next/core-web-vitals',
	],

	settings: {
		'mdx/code-blocks': true,
		'mdx/language-mapper': {},
	},
}

In the extends array, I added 'plugin:mdx/recommended', because I wanted ESLint to recognize that I do indeed have eslint-plugin-mdx npm package installed. And I added the settings object because I wanted to lint code blocks at the same time (optional) by adding 'mdx/code-blocks': true. And for the sake of future potential additions or overrides, I added 'mdx/language-mapper': {} where I could disable the language mapper inside the mapper object. And in my next.config.js file, I already had added:

module.exports = withBundleAnalyzer({
	pageExtensions: ['js', 'jsx', 'md', 'mdx'],
})

Now, when I git commit my changes, I don’t get a linting error because of the unrecognized frontmatter --- data definition in my post files due to my husky pre-commit hook associated with my lint-staged configuration, which then meant that I would be able to achieve a successful commit.

To recap, ESLint is a parser for inspecting code, reporting bugs, coding mistakes, or typos. It is opinionated, so sometimes we have to disable rules in order to be able to make commits.

lint-staged is a package used to run a linter (in this case ESLInt and Prettier) on staged git files and prevent them from committing buggy code.

Husky, as mentioned in other posts here (you can look up “Husky” in the Tags page), is a tool that works with Git hooks such as the pre-commit hook.

Prettier is a tool for formatting code based on its configuration defined in its config file (mine is called prettier.config.js, but it can also be a json file called .prettierrc.json).

Happy linting and successful pre-committing!

Note 12.9.22: The red squiggly line still shows up at the beginning of the beginning of the frontmatter data block represented by the --- triple hyphens, but as mentioned in an esint-plugin-markdown issue entitled Parsing error: Invalid left-hand side in prefix operation in mdx frontmatter #150 on their Github repository,

That parse error suggests that it's trying to parse the --- in the first line of the file as a -- prefix unary decrement operator. That normally wouldn't happen. Is there something in your config that might cause ESLint to parse a .mdx file as JS?
I explained a bit in MDX support #134 (comment), but I don't expect this plugin would work with MDX syntax currently since it's so different from Markdown. Based on a skim of the MDX docs, it shouldn't crash on the syntax, and in fact it shouldn't do anything. The plugin works by looking for ```js fenced code blocks, and since MDX doesn't need those, it shouldn't find any code to pass to ESLint in the first place. My guess is it should treat all the embedded JSX as regular text and ignore it like it ignores all the rest of the file outside of fenced code blocks.
You're probably best using https://github.com/mdx-js/eslint-mdx to lint .mdx files since it's maintained by the MDX team. - btmills commented on Jul 22, 2020

And because of the line 'mdx/code-blocks': true, in the ESLint config file, Eslint lints code blocks in my posts. So they literally have to be error free! Which is actually really good!

Related Resources

Social Share: