How to disable/override limited-exports-page-templates in ESLint?

[TristanPeers]

Hi - we use Gatsby to run an internal docs site. The site is 75% markdown and the rest MDX (with some .js templates). With Gatsby v5 moving to MDXv2 we are having to remove all the MDX elements as v2 is causing us more problems than it does benefits.

We are therefore converting the MDX pages to plain JS. As we use frontmatter and graphql to sort the pages/create structure etc we have started using gatsby-transformer-javascript-frontmatter so that we can have frontmatter in JS to simulate what the MDX pages were allowing us to use.

Everything is working fine except we have warnings in the develop process:

/Users/tristan.peers/tmp/no-mdx/site/src/pages/help/faq/test.js
  3:1  warning  In page templates only a default export of a valid React component and
the named exports of a page query, getServerData or config are allowed.
        All other named exports will cause Fast Refresh to not preserve local component
state and do a full refresh.

        Please move your other named exports to another file. Also make sure that you
only export page queries that use the "graphql" tag from "gatsby".
  limited-exports-page-templates

The test page code for the above warning is:

import * as React from "react";

export const frontmatter = {
 title: "Test",
 description: "Test Page",
};

export default function Test() {
 return <div>Hello World</div>;
}

If I change the code to the other method listed in the gatsby-transformer-javascript-frontmatter example:

import * as React from "react";

exports.frontmatter = {
  title: "Test",
  description: "Test Page",
};

export default function Test() {
  return <div>Hello World</div>;
}

...the warning goes but when you visit the page in a browser, we get:

Unhandled Runtime Error
Close
One unhandled runtime error found in your files. See the list below to fix it:


Error in function eval in ./src/pages/help/faq/test.js:3
exports is not defined

./src/pages/help/faq/test.js:3
Open in Editor
  1 | import * as React from "react";
  2 |
> 3 | exports.frontmatter = {
  4 |   title: "Test",
  5 |   description: "Test Page",
  6 | };

A help request on how to solve this was asked over a year ago, but there are no answers.

According to the Gatsby ESLint docs it is not possible (apparently) to disable limited-exports-page-templates as it is required??

So how do we solve this issue? We have almost 500 MDX pages which will be moved to JS. This means ~500 warnings being displayed which is far from ideal.

Thanks

[LekoArts]

Hi!

we are having to remove all the MDX elements as v2 is causing us more problems than it does benefits

Can you elaborate on this? The MDX v2 update is quite big, the maintainers of MDX changed quite a bit of stuff but so far a lot of people managed the upgrade.

According to the Gatsby ESLint docs it is not possible (apparently) to disable limited-exports-page-templates as it is required??

Yes, that's correct. They have to be there to ensure that Fast Refresh is working correctly. A user opened #35756 to explain that Fast Refresh with the transformer isn't working. I explained there why that happens.

So how do we solve this issue?

I see two paths forward:

• Continue using MDX
• See how you can help @mosesoak in [gatsby-transformer-javascript-frontmatter] Frontmatter export breaks HMR #35756 to contribute a new major version of that transformer to not rely on an export anymore.

[TristanPeers]

Hi @LekoArts - many thanks for responding.

As mentioned this site is predominantly Markdown. As it is a technical docs site there are number of changes in MDXv2 (feature removals) that would make switching very difficult:

1. We can no longer have { or } in the Markdown pages. These must now be escaped and thus cause the build to break. As we have over 50,000 occurrences of these in the markdown pages it is a MASSIVE task to go through the thousands of pages and check each occurrence. Note { or } in markdown code blocks are fine. If we escape the occurrences in code blocks the code is incorrectly displayed as \ is then visible. What I mean is we cannot just search and replace across the whole site.

2. Autolinks are also no longer supported in MDXv2. We have many occurrences of these.

3. Markdown tables are also no longer supported

The time and effort for us to make the Markdown v2 compliant is far greater than converting the MDX to JS.

I would love to be able to help produce a fix, however unfortunately I'm not a developer and only have basic Javascript knowledge.

[LekoArts]

@TristanPeers Oh, my sentence was poorly worded. What I meant:

You can only use .mjs with Gatsby 5. With Gatsby 4 or later you can use the instructions I linked

[TristanPeers]

Hi @LekoArts - many thanks for the above. I worked through all the problematic mdx/markdown and made the required graphql changes and have managed to get the site running on v5 with MDXv2. 🚀

Everything is good except I'm trying to figure out how to enable linting so that we can stop users entering { or } in plain markdown files (.md) as this breaks the build/site.

We use gatsby-plugin-mdx to parse both .mdx and .md, exactly as your docs page says we can.

If I have two test files with un-escaped braces, I can get the linter to properly detect the issue in mdx, just not md:

// test.mdx
---
title: "Test MDX"
---

# Test MDX

{test}

$ eslint src/pages/test.mdx

/Users/tristan.peers/tmp/mdx2_gatsby5/site/src/pages/test.mdx
  7:2  error  Expected an assignment or function call and instead saw an expression  no-unused-expressions

✖ 1 problem (1 error, 0 warnings)

If I do the same with markdown, we get nothing back ie no issues/errors:

// test.md
---
title: "Test MD"
---

# Test MD

{test}

$ eslint src/pages/test.md

This is our eslint config, I've tried to make the markdown (.md) files be treated exactly like mdx but this clearly doesn't work:

// .eslintrc.js
module.exports = {
  globals: {
    __PATH_PREFIX__: true,
  },
  extends: [`react-app`, "plugin:mdx/recommended"],
  settings: {
    react: {
      version: "detect",
    },
    "mdx/code-blocks": true,
    "mdx/language-mapper": {},
  },
  rules: {
    "react/jsx-no-undef": "off",
    "no-undef": "off",
    "jsx-a11y/anchor-has-content": "off",
    "jsx-a11y/heading-has-content": "off",
    "jsx-a11y/iframe-has-title": "off",
  },
  overrides: [
    {
      files: ["*.md"],
      extends: "plugin:mdx/recommended",
    },
  ],
};

Any ideas? I appreciate this is probably more a question for eslint/mdx developers but as you've been so helpful/knowledgeable I thought you may know how to solve this?

[LekoArts]

Great to hear that! Was the migration guide for Gatsby or MDX missing anything? Can we improve the process somewhere?

Unfortunately I only use MDX with .mdx files (see https://github.com/LekoArts/portfolio-v2/blob/14f6aefaa7b36fed1343f5a4ebeb83a2b1804ced/.eslintrc.js#L206-L234) so I'm afraid I can't help with that 😅 Maybe try also defining the parser for the override?

[TristanPeers]

The migration docs were superb as usual @LekoArts ❤️.

One minor thing is that the migration page for v4-> v5 doesn't mention that MDXv2 is now the default. Maybe make it a bit more obvious/clear here?
We were previously on Gatsby v4.10 and only realised this MDXv2 change when we tried launching v5. We'd read the docs but as per above it didn't tell us this.

Many thanks for the tip, I will try adding the parser and then if this doesn't solve it I will ask for help with the MDX/eslint developers.

[LekoArts]

Put up #37485 for it 👍