docs: suggest --bundle when the UI dev server is slow to load By default ui/run-dev-server serves each source file as a separate module, so a page load makes over a thousand requests. Over SSH or port forwarding each request pays the network latency, and the UI can take tens of seconds to load. --bundle serves one bundle instead and loads in a couple of seconds, but the flag is only mentioned in --help. Adds a short section to the UI getting-started guide that says when to use --bundle and lists its caveats: no hot reload, so UI state is lost on every change, and slower rebuilds. It also explains what --no-source-maps trades away.
diff --git a/docs/contributing/ui-getting-started.md b/docs/contributing/ui-getting-started.md index c765992..c2fd0e7 100644 --- a/docs/contributing/ui-getting-started.md +++ b/docs/contributing/ui-getting-started.md
@@ -47,6 +47,32 @@ NOTE: If you made changes to Trace Processor you need to restart the server. +#### If the UI is slow to load + +By default the devserver serves each source file as a separate module, so the +browser makes over a thousand requests on every page load. When the devserver +runs on a remote machine and you reach it through SSH or port forwarding, each +request pays the network latency, and the UI can take tens of seconds to load. + +In that case, serve the bundled UI instead: + +```bash +ui/run-dev-server --bundle +``` + +This loads in a couple of seconds, but it has some caveats compared to the +default: + +- **No hot reload.** Changes are still rebuilt automatically, but the whole + page reloads instead of the changed code being swapped in place, so UI state + such as open tabs or the current selection is lost on every change. +- **Slower rebuilds.** Every change rebuilds the whole bundle, rather than only + the files that changed. + +You can also add `--no-source-maps` to make the bundle smaller still. Without +source maps, stack traces and the debugger show the bundled JavaScript instead +of the original TypeScript sources. + ### Test the change UI unit tests are located next to the functionality being tested, and have