feat(core): allow plugins to customize/override Webpack devServer config

[slorber]

Motivation

We never documented this, but with Webpack 4 there was the ability to just write config.devServer

Since Webpack 5, it does not work automatically anymore with the Node imperative API, and users can't customize easily the devServer.

Instead of adding a new API, I'm merging the user/plugin-provided devServer config to the default one to allow this niche use-case.

Note: Docusaurus users integrating with an API on another domain may find this useful to write a plugin such as:

function ProxyPlugin(context) {
  return {
    name: 'proxy-plugin',

    configureWebpack() {
      return {
        devServer: {
          proxy: {
            '/hey': {
              target: 'https://google.com',
              pathRewrite: {'^/hey': ''},
            },
          },
        },
      };
    },
  };
}

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

local for now, but we should find a way to test the start/devServer workflow better

Fixes #6100

[netlify]

✔️ [V2]

🔨 Explore the source changes: aee1286

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61ba390738df4d0008504836

😎 Browse the preview: https://deploy-preview-6107--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	87
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-6107--docusaurus-2.netlify.app/

[github-actions]

Size Change: 0 B

Total Size: 652 kB

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	37.8 kB
website/build/assets/css/styles.********.css	101 kB
website/build/assets/js/main.********.js	484 kB
website/build/index.html	29.3 kB

_{compressed-size-action}

[Josh-Cena]

@slorber Could this mean that we would be able to test things like ganalytics plugins in dev? By using an Express middleware? Didn't go into WDS deeply, just some wild thoughts

[slorber]

Hmm 🤔 maybe but this means we'll need to re-route GA calls to localhost to log them? Not sure how to do that

This can become quite verbose so not sure it should be enabled by default.

This API could be useful: https://webpack.js.org/configuration/dev-server/#devserveronaftersetupmiddleware

However I'm not sure the merge() fn will merge 2 plugins providing their own onAfterSetupMiddleware impl, and one might override the other 🤷‍♂️

This seems technically possible but not so easy to do it right, and maybe a bit overkill. How users would use this? Is the purpose to just verify that a ga(event) fn is called? IMHO the errors are usually related to bad config, so if we create our own dev-only ga function, that wouldn't help users much debug real problems

[Josh-Cena]

Is the purpose to just verify that a ga(event) fn is called?

Not really—the purpose is to let people actually enable the plugin during dev. Something like this: https://github.com/verdaccio/verdaccio/pull/2772/files could lead to unexpected things leaking into production. Having an identical dev environment would work much better.

[slorber]

What does enabling the plugin in dev mean? How do users would know it's enabled? This plugin could be enabled in dev, but do we really want dev navigations to pollute prod analytics? I don't really understand how this is related to Webpack

I see, we should probably add a warning for usage of themeConfig.googleAnalytics

[Josh-Cena]

So here there are two things:

1. We should probably check with 'googleAnalytics' in themeConfig to prevent even a value of undefined (a very minor improvement though);
2. More importantly is the ability to fully know if ganalytics is running properly during dev. If we can both (a) enable the plugin in dev and (b) not let dev navigations pollute prod analytics by proxying the requests to a local receiver, we reach a true isomorphic behavior.

[slorber]

More importantly is the ability to fully know if ganalytics is running properly during dev. If we can both (a) enable the plugin in dev and (b) not let dev navigations pollute prod analytics by proxying the requests to a local receiver, we reach a true isomorphic behavior.

You can't really know unless you really see the events in the GA console 🤷‍♂️ if you have a proxy, then it might work with the proxy but fail once we send the analytics to the real service.

[Josh-Cena]

Mmm, that's true. The only case this could happen though (that I can think of) is that user has a bad tracking ID, which we can't protect against. But yeah, it was just a wild thought, probably not much useful