feat: router-based wasm bundle splitting (#3683)

* feat: wasm-split base implementation * kinda sorta works with the cli * okay great it actually works * fix: cache busting for chunks * cleaned up version * it works with the router * wip: migrate to a faster linear solution using id remapping * add a good harness * it works completely on the docsite * the super tight build works too * make parallelizable * works on the docsite but not the harness * light cleanups, fix for both harness and docsite * make codegen smaller by extract some shared functions to prevent monos * chunking works, but tbd on tuning heuristics * extract used module * wip: cleaning up module * wip: much better understanding of how imports work * fix the call graph * working again... * wip: thinking about ifuncs * ifunc approach works * yes the ifunc approach works!! * it all works completely even with chunks * small cleanups * comments * actually locate all of the symbols * clean up final implementation * clean up tomls, revert some mono changs * clean up, add some more comments / docs in places * hoist more packages * clean up impl a bit more * clean cli * move harness to playwright * update playwright * extract codgen * add lazy to components * Add docs to split loader * clippy * typos * clippy, don't generate splits if not on wasm * whoops, const * Typos and docs * enable optimizations in ci * add optimizations to ci * add wasm-split router feature * parallel playwright? * fix no case check * disable pre-compress... think that might be the issue * better logging, no default pre-compress, caching of shared symbols * Fix: compressing assets * fix non-interactive logging for serve * cache playwright even on failure, use the cli with optimizations * fix prebuild * fix playwright webserver
2025-02-13 18:54:38 -08:00
1 parent 14eb7597df
commit bdeedc13eb
@@ -97,6 +97,32 @@ fn BlogPost(blog_id: usize) -> Element {

 You need to enable the right features for the platform you're targeting since these are not determined automatically!

+## Bundle Splitting
+
+The Dioxus Router supports automatic bundle splitting along route variants. To enable this, you need to manually turn on the `wasm-split` feature explicitly on the dioxus-router crate:
+
+```toml
+[dependencies]
+dioxus = { version = "*", features = ["router", "wasm-split"] }
+dioxus-router = { version = "*", features = ["wasm-split"] }
+```
+
+Note that `wasm-split` must also be turned on in dioxus since the macro uses the re-exported `wasm-split` from the dioxus prelude.
+
+Enabling splitting disconnects the call graph, meaning if you try to run your app with a normal `dx serve`, it won't work. When running with router splitting, you need to pass `--experimental-wasm-split`.
+
+```sh
+dx serve --experimental-wasm-split
+```
+
+In practice, we recommend passing `dioxus-router?/wasm-split` as a feature only when bundling:
+
+```sh
+dx bundle --features "dioxus-router?/wasm-split"  --experimental-wasm-split
+```
+
+Note that the router will call `.suspend()` so you should add a SuspenseBoundary above the Outlet to prevent suspending the entire page.
+
 ## Contributing

 - Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues).