[gatsby-transformer-javascript-frontmatter] Frontmatter export breaks HMR

[mosesoak]

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/gatsbyjs/gatsby/issues
• This issue is not a question, feature request, RFC, or anything other than a bug report directly related to Gatsby. Please post those things in GitHub Discussions: https://github.com/gatsbyjs/gatsby/discussions

Description

Hot module reload (HMR) doesn't work, using gatsby-transformer-javascript-frontmatter plugin when javascript or typescript files export frontmatter.

This issue has been around since at least Gatsby 3, and continues in Gatsby 4.

Reproduction Link

https://github.com/yallllc/repro-js-frontmatter-hmr

Steps to Reproduce

1. Install gatsby-transformer-javascript-frontmatter plugin
2. Export frontmatter from a page
3. Make a visual change -- style or a jsx -- and see if the page updates on save

Expected Result

Page updates

Actual Result

Page doesn't update.

If the frontmatter export is commented out, HMR will start working again.

Environment

System:
    OS: Linux 5.4 Ubuntu 22.04 LTS 22.04 (Jammy Jellyfish)
    CPU: (12) x64 Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
    Shell: 5.1.16 - /bin/bash
  Binaries:
    Node: 16.14.2 - ~/.nvm/versions/node/v16.14.2/bin/node
    Yarn: 1.22.18 - ~/.nvm/versions/node/v16.14.2/bin/yarn
    npm: 8.5.0 - ~/.nvm/versions/node/v16.14.2/bin/npm
  npmPackages:
    gatsby: ^4.15.0 => 4.15.1 
    gatsby-transformer-javascript-frontmatter: ^4.15.0 => 4.15.0

Config Flags

No response

[LekoArts]

Hi!

This is "working" as expected as Fast Refresh only allows one export per file to work correctly. See https://www.gatsbyjs.com/docs/reference/local-development/fast-refresh/

The documentation at https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-transformer-javascript-frontmatter/README.md needs an update to point this limitation out and link to the Fast Refresh documentation.

[mosesoak]

@LekoArts Thanks for the reply. Just to clarify, are you saying that because the JS Frontmatter plugin requires you to export frontmatter, that it will always break Fast Refresh?

Or is there a syntax that can be used so the plugin doesn't break core Gatsby functionality? Thanks

[LekoArts]

JS Frontmatter plugin requires you to export frontmatter, that it will always break Fast Refresh?

Yes, that's correct. Fast Refresh only allows one export per file.

Or is there a syntax that can be used so the plugin doesn't break core Gatsby functionality? Thanks

If you look at https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-transformer-javascript-frontmatter/src/gatsby-node.js you see that it uses babel to look for these exports. So you can only use another syntax when the plugin is updated which would also be a breaking change.

As the plugin only has around 800 downloads a week we won't spend any time on it in the foreseeable future fixing this, however if you or anyone else wants to put up a PR fixing this limitation we're happy to review it. If not, that's also okay -- then for now the README should be updated.

The export syntax would need to be changed to just a definition with a pretty clear name so that you can easily find it via Babel.

[mosesoak]

I see. It probably has low downloads because it breaks Gatsby fast refresh. 🤷 In general it's a super useful plugin that our team would love to make use of. Not sure we'll have the bandwidth to contribute but thanks for your replies!

[mosesoak]

@LekoArts I got it working! Took your suggestion and modified the plugin so it works without export.

https://github.com/yallllc/repro-js-frontmatter-hmr/blob/custom-js-plugin/plugins/gatsby-transformer-javascript-frontmatter/gatsby-node.js#L88-L99

One caveat is that unless the frontmatter object is used in the component directly, you need to disable eslint for the line. (I couldn't think of any other standard js way to declare it without an export, since React FC's can't use statics.)
https://github.com/yallllc/repro-js-frontmatter-hmr/blob/custom-js-plugin/src/pages/index.js#L4-L18

After porting this to our current project, fast refresh and frontmatter queries are working together now!

(I could potentially PR this to Gatsby if you think it's a decent approach that might be valuable for others. Thanks again for your efforts with the community!)

[mosesoak]

@LekoArts Side question: can you give a little more background on why adding a named export to a page node breaks Fast Refresh -- is that a feature or a limitation? Feel free to point me to a discussion or code reference as I'd love to help your team look into it if it's something to be solved. Thanks!

[LekoArts]

It's a limitation of Fast Refresh, you can also learn more here: facebook/react#16604 (comment)

I'm out this week, I can look at it more next week.

[toxsick]

@LekoArts I got it working! Took your suggestion and modified the plugin so it works without export.

https://github.com/yallllc/repro-js-frontmatter-hmr/blob/custom-js-plugin/plugins/gatsby-transformer-javascript-frontmatter/gatsby-node.js#L88-L99

One caveat is that unless the frontmatter object is used in the component directly, you need to disable eslint for the line. (I couldn't think of any other standard js way to declare it without an export, since React FC's can't use statics.) https://github.com/yallllc/repro-js-frontmatter-hmr/blob/custom-js-plugin/src/pages/index.js#L4-L18

After porting this to our current project, fast refresh and frontmatter queries are working together now!

(I could potentially PR this to Gatsby if you think it's a decent approach that might be valuable for others. Thanks again for your efforts with the community!)

@mosesoak It would be awesome if you could put this into a PR, facing the same problem.

regards