Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docusaurus Faster - For plugins authors #10572

Open
slorber opened this issue Oct 10, 2024 · 2 comments
Open

Docusaurus Faster - For plugins authors #10572

slorber opened this issue Oct 10, 2024 · 2 comments
Labels
proposal This issue is a proposal, usually non-trivial change

Comments

@slorber
Copy link
Collaborator

slorber commented Oct 10, 2024

Docusaurus Faster - For plugins authors

Docusaurus Faster sister issue for plugin authors implementing the configureWebpack() lifecycle hook.

How to migrate your code

The general idea is that you shouldn't import Weppack directly, because... It will always be Webpack.

You should avoid this kind of code:

import webpack from 'webpack';

require("webpack");

What you should do instead is use a dynamic value that will be either Webpack or Rspack:

  • Use currentBundler.instance that we inject in configureWebpack
  • In Webpack plugins, replace compiler.webpack (see example)
  • Other APIs that might be "dynamic"

If your plugin doesn't import Webpack directly and only tweaks a bit the config as data, it will probably work out of the box.

Example diff of a typical plugin that needs to be updated

-import webpack from 'webpack';

export default function (context, options) {
  return {
    name: 'custom-docusaurus-plugin',
-   configureWebpack(config, isServer) {
+   configureWebpack(config, isServer, {currentBundler}) {
      return {
        plugins: [
-         new webpack.DefinePlugin({}),
+         new currentBundler.instance.DefinePlugin({}),
        ]
      };
    },
  };
}

Retrocompatibility

For plugins published on npm, the currentBundler is only injected starting Docusaurus v3.6.

If you still want to keep retro compatibility with older v3 versions, you can write defensive code like this:

export default function (context, options) {
  return {
    name: 'custom-docusaurus-plugin',
    configureWebpack(config, isServer, {currentBundler}) {
      const bundler = (currentBundler.instance ?? require("webpack"))
      return {
        plugins: [
          new bundler.DefinePlugin({}),
        ]
      };
    },
  };
}

Using third-party Webpack plugins

It is possible that third-party Webpack plugins published on npm do not work with Rspack.

Usually, the Rspack team tries to provide built-in plugins for most popular Webpack plugins, and you'll need to integrate them with if/else conditions using currentBundler.name = "webpack" | "rspack".

Here's how we do this: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-bundler/src/currentBundler.ts

As far as I have seen, none of the popular plugins in the Docusaurus community are in this situation. Please let me know what Webpack plugin you are trying to use and we'll figure out a solution.

Examples

Here are a few examples of community plugin PRs to add support:

Good luck!

@slorber slorber added proposal This issue is a proposal, usually non-trivial change status: needs triage This issue has not been triaged by maintainers and removed status: needs triage This issue has not been triaged by maintainers labels Oct 10, 2024
@facebook facebook deleted a comment from krrish-sehgal Oct 14, 2024
@rohit-gohri
Copy link
Contributor

I think the Retrocompatibility example is reversed:

      const bundler = (require("webpack") ?? currentBundler.instance)

but should be ->

      const bundler = (currentBundler.instance ?? require("webpack"))

@slorber
Copy link
Collaborator Author

slorber commented Oct 26, 2024

Definitively, thanks for catching that 😅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
proposal This issue is a proposal, usually non-trivial change
Projects
None yet
Development

No branches or pull requests

2 participants