WebpackModuleFederation is verbose and documented poorly

[Akazm]

I'm currently working on several features demanding abilities like Module Federation should provide. I do need to use the dynamic module federation features specifically. I've encountered several barriers I haven't been able to overcome for several days now, so I decided to fill in a 'complain', hinting at some issues I discovered with provided examples.

Since I don't know how Module Federation works and since I'm unable to use it properly, I'm also unable to provide suggestions on how to improve the documentation specifically.

First of all, I could barely use WebPack's official documentation at all since the documentation itself seems to be unnecessarily verbose, especially on technical details, and does not get to the point on how to use it properly, especially when it comes to TypeScript.

Then, there are the examples, which do have one major issue - When it comes to dynamic modules, you can find on line across the entire Google results list, which is:

const container = window[scope]; // or get the container somewhere else

Several questions come up:

• What is the container?
• Who's responsible for it's lifecycle?
• If it's me, where and how should I create it?
• What's the purpose of the container?
• Why is it undefined per default?

Other than that, as it is almost always the case with WebPack's configuration file, I think the configuration's properties are unnecessarily verbose - and it's again very, very hard to make any sense of them.

new ModuleFederationPlugin({ name: "app2", filename: "remoteEntry.js", remotes: { app1: "app1@http://localhost:3001/remoteEntry.js", } })

• The string 'app2' occurs 2 times within this example configuration. Why?
• 'remoteEntry.js' occurs 2 times. Why?
• What's the point of configuring remotes statically within webpack.config.js? Shouldn't it be espacially focused on dynamic remotes, since development and production environments can be very different from one another?

Please don't interpret this as a rampage, it's just a list of hints. I'm going to try my best to get it to run, but I've decided to share my pain during the process with you guys.

Maybe you'll agree on specific points with me, maybe you don't, none of this is an offence :)

[alexander-akait]

/cc @ScriptedAlchemy Maybe you can use here too 😄

[ScriptedAlchemy]

I can refine the docs a little. However I'm not sure I can reduce the verbosity.

I wrote a 150 page book on MF and that didn't even cover it all.

Definitely can address some of the glaring errors you outlined here though

[alexander-akait]

@ScriptedAlchemy Yep, I understand this, maybe just popular problems and solutions

[ScriptedAlchemy]

@alexander-akait happy to

Will start working on it the following week, traveling at the moment

[daodaoker]

I can refine the docs a little. However I'm not sure I can reduce the verbosity.

I wrote a 150 page book on MF and that didn't even cover it all.

Definitely can address some of the glaring errors you outlined here though

Can you share it? I need relevant documents urgently, thank you

[scott-ln]

This could probably be merged with #4283.

[ScriptedAlchemy]

@daodaoker https://module-federation.myshopify.com/products/practical-module-federation

[peterkmurphy]

The problem I am having with Webpack Module Federation is that while there are lots of neat examples around the web, it is not a substitute for adequate documentation. For example, take this example from here:

https://github.com/paloitsingapore/webpack-module-federation/blob/main/subA/webpack.config.js

Yes, the project works, but when I try to adapt this code to my project:

    new ModuleFederationPlugin({
      name: 'sub_a',
      filename: 'remoteEntry.js',
      exposes: {
        './SubAApp': './src/index',
      },
    }),

I am at a loss because there is no actual API documentation for ModuleFederationPlugin. Maybe that would be a great place to start.

• What does name do?
• What does filename do? What else do I need so the code is available at website/remoteEntry.js (or whatever the filename is) is live, so other people can access it?
• What does exposes do?
• What other properties are there?

There are other things that are necessary, but an API document would be essential.

[peterkmurphy]

After a good night's sleep, I thought I'd add this.

Like many programmers, I trust webpack to do its thing. I'm from React world, with create-react-app to set up the essentials. I don't want to touch the webpack configuration. It works. I don't want to break it.

But microfrontends are starting to be a thing, and so people are looking around, and Webpack Module Federation is one of those technologies that promise to deliver it. It's even more flexible than single-spa - you can run a React App as a container on domainA:portA and have it talk to domainB:portB. But you can't do it with the existing webpack documentation.

So for quite a few developers, Webpack Module Federation may be the first time that they have to change the webpack configuration. They've never needed to do so before. But there comes a time in a programmer's life where it is time to eject or use craco or react-app-rewired or what have you, and Webpack Module Federation could be it. And so ModuleFederationPlugin is one of the first parts of webpack that they will looking for documentation. Do you see the issue here?

That's another reason why ModuleFederationPlugin needs better documentation. Especially the API.

[ScriptedAlchemy]

https://github.com/sokra/slides/blob/master/content/ModuleFederationWebpack5.md

[ScriptedAlchemy]

I've got tons of content about MFP. PR process for webpack docs is a little bit tedious and don't really have time to deal with it.

That said. Some basics like what does each key does on the api could be helpful.

I kind of expected developers to know what filename does tho, but I get the point about cracking open a config for the first time. If you don't know basic options of webpack then it's a little abstract.

[peterkmurphy]

Thank you for getting back to me, @ScriptedAlchemy, and thanks for providing the slides. I guessed filename is the name of a file, and I furthermore guessed the endpoint will occur at ${host:domain}/${filename}. But I am guessing. When I take the code above and put it in another project that I made, I am not getting the endpoint happening.

I set my filename to remoteEntry.js, and point my browser to http://localhost:3000/remoteEntry.js, and I get nothing. I try http://localhost:3000/static/js/remoteEntry.js, and I get nothing either. So why isn't it happening? Yes, filename is for filenames, but the context is missing here.

If there was practical API documentation (like say Redux or React or even Django), then it would tell the reader:

1. What is the purpose of filename
2. If "filename" is required or optional (and if so, what was the default),
3. What other criteria is necessary (such as having a publicPath in output in module.exports, perhaps?) to make it work.

One thing I notice is that ModuleFederationPlugin seems to be doing two things. I've been using it (well, trying to) make my code available to others as a microfrontend. But ModuleFederationPlugin is also used in containers when it is fetching data from microfrontends. I am wondering why two plugins were created instead of one? It would make it easier to document.

Thank you again.

[ScriptedAlchemy]

It's actually 4 plugins under the hood, webpack is mostly just a bunch of plugins. We mostly document the main plugin since nobody really uses the low level plugins independently. It's broken up like that because it's complex and just good software design imo

Options are not required. Technically none are since the api activates different parts of the plugin (sub plugins) depending on what options you add.

Set publicPath to auto. Look in your build output file and see where the remote entry is ending up.

Have you looked at module-federation-examples? Thats the "official" source of reference. If I didn't author the repo you are referencing, there's a high probability it's not done properly.

Webpack is hard to document, I wrote a 200 page book just on federation, still that doesn't cover everything.

This is open source software. React is heavily funded. Redux has a pretty small api. The surface area of webpack is massive in comparison.

If you're stuck DM me on twitter and we can do a zoom call. Take notes and PR the docs.

Not trying to be rude, I can empathize with the struggles. I also have a very deep understanding of webpack. It's hard to document something you built, to me it makes perfect sense lol. I've also been a contributor to webpack since v1 so it's pretty easy to lose grip on the reality of what people know vs what I know.

[peterkmurphy]

Thank you for getting back to me. My point is that I don't (well, didn't) need everything. Documenting an API should not take 200 pages. Perhaps it could take 20 or more pages; I'll concede that. But it shouldn't take 200 pages.

I once wrote a learning guide for CSS that covered quite a lot - paragraph styling, page layout, and even stuff like media queries and font loading; it came to just over 100 pages. Are you going to say that the surface area of Webpack Module Federation (not Webpack, but just the Federation) is bigger than Cascading Style Sheets?

I've been looking at the Webpack API, and none of the subpages come close to 20 pages. You could even start with the existing documentation for the Module Federation Plugin API and actually complete it. I am delighted to see you have runtime and shared in there already. So why not append descriptions of name, filename and exposes as well, and other properties you would use? And if it is actually 4 plugins under the hood, why not copy and paste the APIs of the plugins in there? Or if you are pressed for time, why not write the names of those 4 plugins and tell the reader what they are?

I can't help but notice that there are 77 contributors for the Module Federation Examples, lots of them dated like yesterday. Maybe at least one of those contributors could actually update the API. It could even be you.

[Akazm]

I can't help but notice that there are 77 contributors for the Module Federation Examples, lots of them dated like yesterday. Maybe at least one of those contributors could actually update the API. It could even be you.

He's got a point: Maintaining open source can become tiresome and he does not owe anyone of us anything. It's an issue with Open Source in general that people start to raise their expectations.

Not trying to be rude, I can empathize with the struggles. I also have a very deep understanding of webpack. It's hard to document something you built, to me it makes perfect sense lol. I've also been a contributor to webpack since v1 so it's pretty easy to lose grip on the reality of what people know vs what I know.

And I think that is an issue with webpack in general. It's powerful, useful, but full of people with specialized niche knowledge, which they themselves seem to consider to be common knowledge. Webpack config files speak volumes of this, they're almost incomparable to anything else I've seen out there (but somewhat more powerful as well).

[peterkmurphy]

Of course he doesn't owe us anything, @Akazm. But I'm trying to hint pretty strongly that he actually has some control over whether Module Federation is used or not, one way of getting stuff into the used column is actually providing useful documentation, and here's a way forward that suggest themselves. There's enough documentation on Webpack itself, which is used hundreds of thousands of times a day around the world. Perhaps the problem here isn't not understanding webpack?

[Akazm]

Of course he doesn't owe us anything, @Akazm. But I'm trying to hint pretty strongly that he actually has some control over whether Module Federation is used or not, one way of getting stuff into the used column is actually providing useful documentation, and here's a way forward that suggest themselves.

I basically agree with you on this, that's why I did submit this issue in the first place :).

But eventually, it's up to him or any contributor to acknowledge this issue or to leave it untouched. I've given up on trying to use Module Federation a while ago and I'm totally fine with that without expecting anything.

There's enough documentation on Webpack itself, which is used hundreds of thousands of times a day around the world. Perhaps the problem here isn't not understanding webpack?

It isn't.

[ScriptedAlchemy]

I’ll opening a pr, will reference this thread - could use some guidance one what’s helpful or missing. During the review.

yeah 77 contributors to the MF examples but very few work on webpack itself unfortunately.

200 page book, fair point. But what the api keys are vs leveraging the mechanism is very different. That said an extra paragraph would probably save users a lot of time and head scratching.

Sorry to hear you’ve given up on using the plugin. Issue acknowledged

[Akazm]

I’ll opening a pr, will reference this thread - could use some guidance one what’s helpful or missing. During the review.

Could you add a link here in case GitHub won't notify us?

Sorry to hear you’ve given up on using the plugin. Issue acknowledged

Don't worry about that, it's not your fault, it's my own laziness.

[peterkmurphy]

@ScriptedAlchemy: I am very pleased that you are opening a PR. I would also be willing to help with guidance and wording.

One bit of advice I'd add is maybe add a one or two line summary of what Webpack Module Federation does to the official docs, before you start with the Motivation. Something like:

Webpack Module Federation allows your application to compile JavaScript code from other Webpack modules running on a separate host. That allows your application to use another as a microfrontend.

As for using Webpack Module Federation, my organisation won't be using it now, but we may revisit our decision in three or six months' time. We've just had a research spike on microfrontends, because we are looking at running out a suite of applications with a common container application; technology used is React+Redux+TypeScript+React Router+Material UI, for your interest. We looked at quite a few things, even iframes.

As it stands, we can get webpack for one React application to get the JavaScript files at another host; it's stable most of the time, but every now and then Redux complains about createStore being called multiple times. Our approach is based on this Cam Jackson article with some advice from this Jennifer Fu piece about React apps that start their lifetime from Create React App. (Rather than use react-app-rewired, we are using craco, as it seems to be better maintained.) We might go well with the approach, but I will still have Webpack Module Federation in the back of my mind.

I should add that there's one more reason why we (and others) may be making or revising microfrontends decisions in the near future. We use apps bootstrapped from Create React App, which uses Webpack 4; and many other groups. However, Module Federation comes with Webpack 5. CRA will be going Webpack 5 real soon now... except that there are still some milestones to pass before the thing rolls into production. By the end of the year? Almost definitely.

Anyway, I am delighted that you are opening a PR, and yes, I'd love to help.