Upgrade to MDX 2

[shepmaster]

↪️ Pull Request

This upgrades the dependency on MDX to version 2.

💻 Examples

Previous MDX examples should still be applicable.

🚨 Test instructions

Previous MDX tests should still be applicable.

✔️ PR Todo

• Added/updated unit tests for this change
• Filled out test instructions (In case there aren't any unit tests)
• Included links to related issues/PRs
• Discuss how the potentially breaking change from 1.x to 2.x should be handled.

[devongovett]

Hey thanks for working on this. I think the big question is how we release it since MDX v2 has breaking syntax changes. We would also prefer not to bump a major version of all of Parcel just for this though.

Two options:

1. Release this as a new plugin, e.g. @parcel/transformer-mdx-v2. Users would need to manually opt-in by installing the plugin themselves and adding it to their own .parcelrc. That would work but not that optimal.
2. Bump a major version on @parcel/transformer-mdx. Change the dependency range in @parcel/config-default to e.g. ^2.4.1 || ^3.0.0. This way, existing projects will continue to work with the old version and would need to manually update the version installed in their projects, but new projects would automatically get the latest when auto installed. I think this is more optimal, but I have not tested whether it will actually work at the moment or whether we need to make changes to support it.

[axe312ger]

2. Bump a major version on @parcel/transformer-mdx. Change the dependency range in @parcel/config-default to e.g. ^2.4.1 || ^3.0.0. This way, existing projects will continue to work with the old version and would need to manually update the version installed in their projects, but new projects would automatically get the latest when auto installed. I think this is more optimal, but I have not tested whether it will actually work at the moment or whether we need to make changes to support it.

From a user perspective, that would preferred. Having two separate packages will introduce confusion and people ending up with MDX 1 in 2023

[Ayc0]

Feature request:
This plugin should have the possibility to have a 2nd argument options, like the webpack loader: https://mdxjs.com/packages/loader/#options (so that if people want to add custom remarkPlugins or other options, they'll have the possibility to)

[Ayc0]

as similar system as done in the Stylus plugin could be used: https://github.com/parcel-bundler/parcel/blob/a6765b2/packages/transformers/stylus/src/StylusTransformer.js#L18-L26

We try to load a .mdxrc.js or .mdxrc.cjs or .mdxrc.mjs file and if found, we disable the config on load with config.invalidateOnStartup(); and this config is then passed to the mdx compiler as a 2nd argument.

[Ayc0]

Two options:

1. Release this as a new plugin, e.g. @parcel/transformer-mdx-v2. Users would need to manually opt-in by installing the plugin themselves and adding it to their own .parcelrc. That would work but not that optimal.
2. Bump a major version on @parcel/transformer-mdx. Change the dependency range in @parcel/config-default to e.g. ^2.4.1 || ^3.0.0. This way, existing projects will continue to work with the old version and would need to manually update the version installed in their projects, but new projects would automatically get the latest when auto installed. I think this is more optimal, but I have not tested whether it will actually work at the moment or whether we need to make changes to support it.

What about:

• introducing a new mdx-1 package that would be a repost of the currently existing mdx package,
• keep the current mdx package and make it point toward mdx-1 for retro compat
• introduce a new mdx-2 package for mdx 2,
• in the next major of parcel, we remove mdx-2 and change mdx to work with mdx-2 and not mdx-1 anymore (and maybe keep mdx-1)

The issue with just introducing mdx-2 is that if MDX upgrades the v3, we maybe not want to introduce a new mdx-3 package but only keep it as mdx (if they follow Angular's style for major upgrades).
Also, if I'm correct, most of the @parcel/transformer-* packages have the same versions as parcel's. So it could be weird that just @parcel/transformer-mdx would follow a different versioning system.

[guoyunhe]

Maybe for Parcel 3? I saw Vite release major version quite often (less than a year). Maybe Parcel can take similar approach. In this way, new projects always get new features and old projects are not affected. Nobody needs to manually configure anything to opt-in or opt-out.

Having *-2 or *-3 packages doesn't feel right... Looking at Vite, its core and plugins have different versions, and they release separately. It is more flexible when adopting breaking changes.

[shepmaster]

With Parcel 2.9's local plugins, I found it easy enough to have my own little plugin that does exactly want I need it to do:

.parcelrc

{
  "transformers": {
    "*.mdx": ["./parcel-transformer-mdx2.mjs"],
  },
}

parcel-transformer-mdx2.mjs

import { default as ThrowableDiagnostic } from "@parcel/diagnostic";
import { Transformer } from "@parcel/plugin";
import { compile } from "@mdx-js/mdx";

export default new Transformer({
  async transform({ asset }) {
    let source = await asset.getCode();

    let codeVFile;

    try {
      codeVFile = await compile(source, {
        development: true,
        jsx: true,
        providerImportSource: "@mdx-js/react",
      });
    } catch (e) {
      const { start, end } = e.position;

      const highlight = {
        message: e.reason,
        start,
        end,
      };

      if (!(end.line && end.column)) {
        highlight.end = { ...start };
      }

      // Adjust for parser and reporter differences
      highlight.start.column -= 1;
      highlight.end.column -= 1;

      throw new ThrowableDiagnostic({
        diagnostic: {
          message: "Unable to compile MDX",
          codeFrames: [
            {
              filePath: asset.filePath,
              code: source,
              codeHighlights: [highlight],
            },
          ],
        },
      });
    }

    let code = String(codeVFile);

    asset.type = "jsx";
    asset.setCode(code);

    return [asset];
  },
});

It would be great if Parcel supported this out of the box, sure, but I'm no longer blocked on upgrading my dependencies now.

[TechQuery]

I publish a MDX 3 transformer plugin, which may be help: https://github.com/EasyWebApp/Parcel-transformer-MDX