Documentation for migrating plugins from Docusaurus 2 -> 3

[johnnyreilly]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

I'm testing out the Docusaurus 3 alpha here: johnnyreilly/blog.johnnyreilly.com#601

Unfortunately plugins have been broken by the migration; likely related to ESM - is there any guidance / examples around migrating plugins to Docusaurus 3 please?

I get this error:

Error [ERR_REQUIRE_ESM]: require() of ES Module /home/john/code/github/blog.johnnyreilly.com/blog-website/node_modules/unist-util-visit/index.js from /home/john/code/github/blog.johnnyreilly.com/blog-website/image-fetchpriority-rehype-plugin.js not supported.
Instead change the require of index.js in /home/john/code/github/blog.johnnyreilly.com/blog-website/image-fetchpriority-rehype-plugin.js to a dynamic import() which is available in all CommonJS modules.

It sounds like it's trying to be helpful with this error message, but I haven't succeeded in taking this advice and turning it into working code 😢

Self-service

• I'd be willing to address this documentation request myself. (If I knew how)

[slorber]

Hi

No particular guidance apart the one that goes with any MDX update: all unified dependencies have changed to adopt to MDX 2.

The error mentions unist-util-visit is an ESM plugin so your CJS plugin needs to either import it with a dynamic import, or be itself an ESM module.

I would use ESM for your plugins so that you can use import, and then import your plugins dynamically in the Docusaurus config file.

https://docusaurus.io/docs/next/api/docusaurus-config

module.exports = async function configCreatorAsync() {
  const myPlugin = (await import('./myPlugin')).default;
  return {
    // site config...
  };
};

Similar to what is done for newer Remark math versions here: https://docusaurus.io/docs/next/markdown-features/math-equations#upgrading-rehype-katex-beyond-recommended-version

I documented this a bit better already for v3, but due to Crowdin issues our website refuse to deploy for a long time... 😓

You would also need to read carefully this PR: #8288

I will try to write more docs and fix the website deployment soon.

Going to close because this is probably better asked in our dedicated MDX 2 upgrade support discussion: #9053

[slorber]

A support discussion for Remark/Rehype plugin authors: #9337