The Perils of Gatsby MDX Setup

I spent sometime trying to get Gatsby set up here on this blog, and had a few problems getting Gatsby to work. I wanted to use MDX files for my posts, which from what i gather, allows you to insert react components directly into your markdown files. I encountered a few obstacles:

1. Dependency Hell

   • Constant version conflicts between gatsby-plugin-mdx, @mdx-js/react, and other packages
   • Endless ERESOLVE errors during installation

   npm ERR! code ERESOLVE
   npm ERR! Could not resolve dependency: @mdx-js/react@"^3.1.0"
   

I ended up just restarting from scratch completely (gatsby new), somehow I had gotten the mdx dependencies completely mixed up. After starting from scratch, I still ran into some issues, but at least npm install worked again.

2. GraphQL Quirks
   • Mysterious Cannot query field "allMdx" errors
   • Schema conflicts between MDX and regular Markdown

This was from following a tutorial that converted a normal md blog to mdx, it seemed like I missed a few allMdx string replacements.

3. Component Confusion

   • Element type is invalid errors due to:
   • Incorrect component imports/exports
   • Case sensitivity issues in file paths
   • Missing parent components like Layout

   In the end, I think this had to do with the Mdx component that I was referencing, which was incorrectly imported into the project.

4. Path Problems

   • Double /blog/blog/ in URLs from slug generation issues
   • 404 errors due to incorrect page creation

This may have been due to a suggestion from Claude which recommended to keep "blog" prefix in one of the template files. It took a while to figure out

The Solutions We Tried

// Switched to plain Markdown in desperation
module.exports = {
  plugins: [
    `gatsby-transformer-remark`, // The hero we needed
    {
      resolve: `gatsby-source-filesystem`,
      options: { path: `${__dirname}/src/posts` }
    }
  ]
}

Other fixes included:

• gatsby clean is a useful command that seemingly fixed some things, but not always. I started using gatsby clean && gatsby development by the end of it.
• Manual cache deletion when Gatsby got stubborn
• Hours of comparing config files line-by-line
• Restarting from scratch at least twice

Final Conclusion

Ultimately I switched to regular Markdown files, not a terrible compromise, but will be unable to use react components.