Static HTML + Full React DOM - Is this expected #11184
Replies: 1 comment 5 replies
-
Docusaurus Faster initiative but somehow I am puzzled if I might be doing something wrong or it might be better to change my approach. The more pages you have, the more time it takes: that's something common with all static site generators. Static site generators based on frontend framework/routing offer a nice modern navigation experience, but are also usually slower to build per page than pure server-only static site generators. Why don't you try Docusaurus Faster? With recent improvements, I've seen large sites building 3-4x times faster recently. If you don't share more details (number of input docs, build times etc) it's hard to tell if there's a problem or if it's expected.
It's unclear if you speak of input files (not under our control) or output files (in
This is how React SSR/SSG historically works, and Docusaurus is not doing anything different from any other React SSR/SSG framework:
Yes, you'll see exactly the same using Next.js, Remix, Gatsby
There are many reasons for that:
You didn't trigger it, it has always been like that
Thanks, and I'm sure you'll find recent improvements will make your site build much faster. Before rethinking anything, maybe try to use Docusaurus Faster.
Use Docusaurus Faster Use this env variable to print more "performance-related logs" and see which step takes time. export DOCUSAURUS_PERF_LOGGER=trueRelated, but regarding the "duplication" of html/js content. This only affects the initial page load, not subsequent navigation. It's a React problem, not Docusaurus. React needs the JS code to hydrate to the existing HTML page (which as we have seen, should rather be pre-rendered). Many other frameworks work like that (apart Qwik, which is quite different). I think in the future, supporting React Server Components in Docusaurus. As of today, I think the duplication is still there, but you'll still be able to have much lighter JS files. There's various feedback online about improvements, for example: https://www.mux.com/blog/the-building-blocks-of-great-docs It will take a while before we support RSCs, but I plan to start working on it as soon as v4 is out. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for the general insight. As I'm mainly using React (and related SSR) technologies as part of Docusaurus I'm rather unexperienced in the details of how things work in the ecosystem. It's good to know that I'm not generally doing something wrong and the duplication is expected 🥳 . But also sad to hear that I'm hitting the same bottlenecks which are quite general and hard to solve 😣
rspack is not compatible with a WebPack plugin I need. As far I could find out there are no plans by rspack to add the related APIs required for my plugin to work (parser hooks, module depencencies,..). 😭 Its my own plugin but its currently not feasable for me to develop a rspack plugin in Rust. I'm still hoping for the day where all bundlers and frameworks properly support Web Workers and Audio worklets. Until then I'm forced to teach the bundlers how to do things as I need it.
Here some numbers 😉
Resulting in:
Eespecially the huge auto generated menu tree and some custom syntax highlighting bloat my pages.
Are there strategies available in Docusaurus where the HTML could be rendered more lightweight and once React loads, the page is extended? I'm thinking:
For my own content components I could maybe try to handle things accordingly. But there is still the sidebar I have to tackle.
SEO is indeed a valid topic I was neglecting. I personally could live that some specific areas of my reference docs are not indexable. My website is showcasing a Music Notation library (JS and other platforms) and is generally heavily relying on scripting aspects (playgrounds, live demos etc.) Hence my target audience does not really include people disabling JavaScript 😁
I looked at the logs already a bit, but didn't profile deeper yet what exact parts of WebPack (or other tools) cause the slowness. |
Beta Was this translation helpful? Give feedback.
-
I understand. But you probably don't need to implement a Rust plugin to bring Rspack support for your plugin: it's possible that using existing JS apis would be enough. Sometimes the Webpack plugin can be implemented in a different way, which makes it compatible with both bundlers. I'd try refactor it and see how it could be implemented differently, using APIs supported by both.
I don't understand, how do you see that bloat exactly? If you have many docs, they all appear in your sidebar, and we can't really do anything about it.
In any case, you can decide to swizzle and wrap our components with the Also note that Docusaurus already has a "lazy" strategy for the sidebar, and it will only server-render the currently displayed sidebar slice. If you load a page for an item in Sidebar category 1, the sidebar category 2 items will not be pre-rendered in the initial HTML (unless you mark it explicitly as opened by default). We try to reduce the amount of pre-generated HTML while also preventing layout shifts and ensuring that it's still possible to navigate if JS fails to load (progressive enhancement). TLDR: If you split your sidebar in multiple categories, your pages HTML should become smaller automatically.
If you don't care much about SEO, using the hash router turns your app into a full client-side SPA: https://docusaurus.io/blog/releases/3.4#hash-router---experimental
People disabling JS is not the most common problem. Think also about people that are in a train, or a poor country, and will see a blank page, or can't click links until React code has loaded. For some of them, loading all the JS that may be required can take a long time, and the UX might be misleading. Read http://kryogenix.org/code/browser/everyonehasjs.html Docusaurus tries to use progressive enhancement whenever possible. If JS didn't load (yet), most of the content should remain available, and links should permit to navigate.
[PERF] Build > en > Load site - 1.91 seconds! - (58mb -> 117mb)
[PERF] Build > en > Bundling with webpack - 292.57 seconds! - (130mb -> 1975mb)
[PERF] Build > en > SSG > Generate static files - 130.63 seconds! - (1981mb -> 2375mb)
[PERF] Build > en > postBuild() - 6.06 seconds! - (2375mb -> 2472mb)
[PERF] Build > en - 432.80 seconds! - (58mb -> 2486mb)You can see here that bundling is the slow part of your build, taking 292s/432s / 67% of your build time. Note that we use Webpack persistent cache so a "cold build" (running If you can't use Rspack, you can still use Docusaurus Faster, many improvements also work with Webpack, and more improvements are coming in v3.8. You can also use Rsdoctor to see what's slowing your build, it also works to analyze webpack bottlenecks: https://docusaurus.io/blog/releases/3.6#rsdoctor-plugin |
Beta Was this translation helpful? Give feedback.
-
The plugin is an adaption of the built-in Web Worker plugin which (I assume) is already using the best practices and required APIs accordingly. Its unlikely I can invent an alternative means of implementing the plugin.
With the insights you shared, there is no "bloat" which is not technically expected. Nevertheless it feels bloated from a matter of size, duplication and compile time. The raw sources of my docs just have ~9MB. After compilation I see a total of ~170MB as result. Even when running
Thanks for all the hints. I will need to dive generally deeper to find out what is causing the durations exactly. Even when running In the "Client" progress bar it mentions ~16000 dependencies & ~5000modules being touched in the process. Thanks for all the help. 🙇♂️ I think from here its my job to dig deeper and hopefully find the root cause. I'll share any relevant insights I can find here 😉 |
Beta Was this translation helpful? Give feedback.
-
I don't know which plugin you are referring to. Please share the link and check that the upstream plugin didn't add Rspack support recently. As far as I understand your plugin is: https://github.com/CoderLine/alphaTab/tree/develop/src/webpack I'm not sure from what plugin it was adapted, but if it was adapted from a popular plugin, it's likely that the Rspack team made the source plugin compatible, or may want to.
I'm not sure what to answer here, I try to do my best with the constraints and design we have but it's unlikely we'll ever reach a point that doesn't feel bloated to you unless we stop using React and building a single-page application. You can try tools like Hugo, Eleventy or Astro if you want something that feels more lightweight and reduce client-side JS. If you want a modern SPA navigation experience, you have to run some JS locally that takes more space than raw strings, and Docusaurus itself has its own runtime and templates. Some of those strings may appear in multiple places (for example, when using tags, authors and paginated views). In any programming language, it's unlikely that the distribution output of the "hello world" program is smaller than its minimal string input.
That's unfortunate. I can't tell why it's so slow, but even with Webpack it's surprising that recompiling is not faster thanks to the incremental cache. |
Beta Was this translation helpful? Give feedback.
-
We might be drifting a bit off-topic but if you're interested into deeper insights I wrote some sentences around this point 😉 Read more
Yes, my own plugin is located in https://github.com/CoderLine/alphaTab/tree/develop/src/webpack. While WebPack exposes the required APIs, RSPack does not expose them. Already the biggest blocker is the absence of Parser Hooks, allowing you to tap into the AST and react by rewriting the code or generating new stuff where they have no plan to support it. See 1 See 2. In the Rust-space of RsPack all bits would be available but its a big step to implement this. I haven't seen any bundler in the market which supports both Web Workers and Audio Worklets out-of-the-box (WebPack, RSPack, Rollup, ESBuild) and adding support via plugins is a tough job. Some bundlers have a good JavaScript API surface to implement the required bits (WebPack & Rollup), and some require other technologies to react that deep ( RSPack - Rust, ESBuild - Go). The related issues in the upstream projects are only slowly progressing. On top of the bundlers come frameworks (Angular, React, Vue) which again ship their own custom configs making it hard to consume and configure the required extensions (I'm looking at you Angular 👀). As soon as you import further modules or dependencies they start to break. Often users are forced to make very specific framework, bundle and chunk configurations in the consuming project for things to work as expected. Something I'd like to avoid for my project. I am regularly thinking on how I could workaround these problems within my library to rely on only built-in functionality. My project also carries its load of tech-debts where I plan to be backwards compatible.
According to my first profiles its having a tough time in building the whole module and chunk graphs. Luckily Node.js can be used together with the Blink DevTools, performance profiling is no problem. Finding the root cause will be the challenge. One CTRL+S after a loaded website with My best guess currently is that "something" traverses/loads all docs even though only one file was touched. By this thousands of files/modules have to be handled by webpack every time. I ruled out the sidebars already by removing the generated pages from the sidebars. On clean builds I saw a suspicious amount of errors raised when loading/parsing the MDX. Invalid substrings are fed into acorn for parsing causing internally errors to be raised. There is a problem with thousands of exceptions thrown.
Will report back once I have some real findings. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
I lately started to auto-generate many docs from my TS Docs into MarkDown pages for people to use.
As you might expect this quickly bloated my page and compilation times spiked. I am aware of the Docusaurus Faster initiative but somehow I am puzzled if I might be doing something wrong or it might be better to change my approach.
I was shocked to see how the file count of my website exploded and I noticed a wierd thing:
assets.jsoutput containing the "react component" flavor of my pages (likely for https://docusaurus.io/docs/markdown-features/react#importing-markdown?).Is this really the expected behavior? For the dynamic components of the pages (like Tabs), React is anyhow needed. Then why I should pre-render the pages to HTML at all? Sure, pages might render a bit faster as the initial DOM is available, but considering the duplication it might be better to just go for a "compiled React SPA website" and accept a bit more initial render time than having a heavyweight HTML per page which anyhow needs to use react afterwards.
At this point I think I just might have messed up my website somehow to trigger this behavior.
npm i && npm run generate-alphatabdoc && npm run build && npm run serveI still love Docusaurus and would like keep using it. But if that's the expected behavior I have to rethink how I manage my generated reference docs.
Any feedback is welcome on how I could troubleshoot this 😁
Beta Was this translation helpful? Give feedback.
All reactions