This library is unmaintained

[jescalan]

Hi friends. I regret to inform you all that this library is no longer actively maintained. We have moved on to using next-mdx-remote, which is much faster, fits more use cases, and is more configurable.

If anyone would like to volunteer to step up and maintain this library, please respond here. Otherwise, use this at your own risk. It is specifically not compatible with webpack 5, and as soon as next.js defaults to webpack 5 as its native dependency, this library will not work with that version of next.js at all.

[Luttik]

Hi @jescalan,

Would it be possible to document a migration path from this library to next-mdx-remote? I know that this package has often been referenced in the context of writing blogs, so it didn't draw the deepest of nextjs experts...

[jescalan]

The readme for next-mdx-remote should provide all the info you need. It even has a section about blogs and links to an official nextjs example implementation. There is not really a single "migration path" exactly - the libraries are dramatically different, and the way that the data flows through your app will need to be restructured.

[Luttik]

The facts that data flows need to be restructured and that there is no "single" path are the very reasons why I believe a migration document would be so valuable. It would provide next-js laymen with an opinionated method to hopefully end up with a supported situation that is just as easy as this library was. If you ask me the next-mdx-remote docs are so much more complex than the docs of this lib that they are simply incomparable.

[Luttik]

If you'd be willing we could work on this together and publish it in the readme of both repos. I could ask the dumb questions that I think many people have and we could fill them in together to at least get a document that give people mental models of what belongs where when moving.

[jescalan]

@Luttik sure happy to answer any questions you have through the process - thanks for volunteering to help with this!

[Luttik]

I have opened the draft pull request #104 to discuss this topic.

[thunder-coding]

I faced webpack errors as mentioned above. And currently there is no workaround except disabling webpack 5. But the only thing that makes me from migrating to next-mdx-remote is the lack of import/export

[jescalan]

@thunder-coding This sounds like it's expected based on the initial comment in the issue. I'm sorry that you are having this problem though. Contributions are welcome to either library!

[Luttik]

@thunder-coding could you clarify what you are missing in terms of import/export ( I guess you're not talking about the js feature...). Maybe that is something that we need to clarify in the migration document too.

[thunder-coding]

I will be migrating to https://github.com/kentcdodds/mdx-bundler . This seems to be a perfect replacement for my use case.

And about the things that I am missing without next-mdx-enhanced:

• Common layout for all MDX Pages
• importing .tsx components

[jescalan]

Just to clarify, creating shared layouts for pages is possible with mdx-remote, as is making components available for use within pages. Both of these are demonstrated in the readme. What it does not currently support is using the import keyword within a given page to import a specific component to that page only. mdx-bundler does support this as long as you read the file's contents and pass it to their config along with its import path. Using mdx-bundler would likely be the better choice if you have a bunch of different pages all importing unique components. If this is not the case however, you might end up with larger bundles and slower performance, since mdx-bundler has much larger output by default (4x the size with a basic markdown page), and it does not, as far as I know, dedupe components shared between multiple pages, which mdx-remote does because the only way to use a component is to have it available with all pages for a given layout.

[ericclemmons]

I just wanted to say thanks for creating next-mdx-enhanced.

I was using next-mdx-remote, but ran into so many issues (mainly with "leaking" every page's components that the build become very slow) that I adopted next-mdx-enhanced for the common layout & frontmatter parsing.

I'll do some more research before adopting mdx-bundler, but I have to say that this project solved a real need that isn't answered better anywhere else today 💖

[jescalan]

@ericclemmons this might be helpful! https://github.com/vercel/next.js/tree/canary/examples/with-mdx-remote#conditional-custom-components

[Luttik]

I just wanted to say thanks for creating next-mdx-enhanced.

I was using next-mdx-remote, but ran into so many issues (mainly with "leaking" every page's components that the build become very slow) that I adopted next-mdx-enhanced for the common layout & frontmatter parsing.

I'll do some more research before adopting mdx-bundler, but I have to say that this project solved a real need that isn't answered better anywhere else today 💖

@ericclemmons That was/is something that really want too. It seems to fit in the theme at we saw with comparing next-mdx-enhanced with next-mdx-remote too, where technically next-mdx-remote seems to be able to do just about anything, but requiring more boilerplate code, more complexity, and a less nice API...

[jescalan]

@Luttik -

I will tell you that there are a LOT of problems with the pattern that mdx-enhanced uses for loading markdown - builds are a huge amount slower than mdx-remote, bundle sizes are much larger, and it can only load local content. Eventually if your site keeps growing, the memory needs to be able to build the site will exceed several gigabytes because of the way webpack internally stores mdx file metadata.

That being said, if it works for your current needs, you are welcome to keep using it. The reason we are not maintaining it anymore at HashiCorp is because its a tool of very limited use, since it does not fit the needs of any remotely large or complex website or app. If your goal is to grow your website at all, you are shooting yourself in the foot by adopting this library, since you will eventually outgrow its capabilities, and you will pay a performance cost along the entire path to that.

We are 100% open to contribution on this library, and also open to suggestions for API changes in mdx-remote, if you think that either one can be changed for the better. That's what open source is all about!

[Luttik]

@jescalan I understand, sorry if I was too frank. I'm still exploring the options and try to communicate my thoughts fully in this thread. As I eluded to before Im one of those that don't have the time to follow the frontend trends deeply.

Since you stated that the patterns of mdx-enhanced were the issue (I guess that is instead of having the implementation being the issue) do you see the same issues with mdx-bundler?

[jescalan]

@Luttik no, but mdx-bundler's API and implementation are nearly identical to mdx-remote, so I'm not sure it will solve a lot of your concerns.

The main difference is that mdx-bundler produces much larger bundles for basic content, by my testing ~4x larger. The feature it offers that mdx-remote does not is support for import statements, but in order for these to work, you need to pass a map of file names and file contents as a string to the configuration for each page that includes imports, which is a very verbose and clunky way to do it. We are also planning to add support for imports to mdx-remote at some point in the next several months and our plan is to have them work out of the box without needing to read files or pass anything to the config.

The only reason IMO to pick up mdx-bundler over mdx-remote is if you are running a site that uses a large number of different components across a large number of different posts, and almost none of your posts share the components they use - in this case you probably would get an edge on bundle size output. Even if you are doing this, you could still make mdx-remote work for you with this technique, which we can deprecate whenever we release support for imports. Usage stats might also be of interest to you here.

Ultimately though, you should just use what you like, as long as the project you're working for is your own project and not on behalf of a company, and as long as the size and scope of your project is small. If this is the case, the stats don't matter that much, and what really matters if you experimenting with different tools, and learning.

[Luttik]

@jescalan I think that is really valuable info for those who are migrating! Thanks

[Luttik]

@jescalan I have some time again to work on the migration guide. I wonder why the technique for heavy components is only suggested for heavy components. Is it a bad idea to use that approach for áll components (given no namespace issues)? Or is that totally fine?

[jescalan]

Yes, that would be a bad idea - dynamically loaded components are not server rendered and cause slower page performance because of this. I would only resort to this approach if you are having performance or bundle size issues.

[Luttik]

@jescalan Maybe the wrong place for this question (and maybe a dumb question altogether...). But wouldn't bundle-size and runtime performance be unaffected if you apply the trick within getStaticProps? Something like:

import dynamic from 'next/dynamic'
import Test from '../components/test'

const SomeHeavyComponent = dynamic(() => import('SomeHeavyComponent'))

const defaultComponents = {Test}

export function SomePage({mdxSource, components}) {
    return <MDXRemote {...mdxSource} components={components} />
}

export async function getStaticProps() {
    const source = `---
      title: Conditional custom components
      ---
    
      Some **mdx** text, with a default component <Test name={title}/> and a Heavy component <SomeHeavyComponent />
      `

    const {content, data} = matter(source)

    const componentNames = [
        /<SomeHeavyComponent/.test(content) ? 'SomeHeavyComponent' : null,
    ].filter(Boolean)

    const mdxSource = await serialize(content)

    const components = {
        ...defaultComponents,
        SomeHeavyComponent: componentNames.includes('SomeHeavyComponent')
            ? SomeHeavyComponent
            : null,
    }

    return {
        props: {
            mdxSource,
            components,
        },
    }
}

[jescalan]

Give it a shot and find out! I think you will likely have issues with the dynamic import within getStaticProps, since dynamic imports are intended for use on the client side but its worth a try!

[arn4v]

This might be of interest to those migrating away from next-mdx-enhanced:

I've written a library called next-mdx-builder that is similar to next-mdx-enhanced in usage but uses next-mdx-remote underneath to build your MDX and supports Next.js 11 (which uses Webpack 5 by default).