droboticflow/docs/frontend-first-screen-performance.md
2026-11-02 07:54:34 +00:00

59 lines
3.2 KiB
Markdown

# Frontend first-screen loading
This change moves non-critical modules out of the eager application entry and
onto the chunks that actually render them. No page markup, interaction or
styling rule changed; only when a resource is fetched.
## What left the first screen
| Resource | Before | After |
| --------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
| `lucide-react` (`icons-vendor`) | Statically reachable from the entry through `Layout`, `Sidebar`, `PluginRouteGuard` and `UserBootstrapPanel`, so the entry preloaded the union of every icon used by all lazy pages. | The eager shell uses `src/components/shell-icons.tsx`; the icon vendor chunk is only requested when a route that imports lucide renders. |
| `Sidebar` (navigation JSX, supplier/users helpers) | Bundled in the entry and parsed on every first paint. | Dynamic `import("./Sidebar")`, warmed only when `droboticflow.currentUserId` already exists. |
| `src/styles/capture-workspace.css` | Imported by the global `src/index.css`, so every page downloaded the annotation workspace layout rules. | Imported by `CaptureAnnotationWorkbench`, emitted with the annotation route CSS. |
| `WorkforceStatisticsPanel` | Bundled in the lazy Dashboard chunk even though it only renders in the collapsed legacy overview. | Lazy import inside a local `Suspense` boundary. |
The eager shell now contains only React, React DOM, React Router, the context
providers, the API client, `Layout`, the plugin guard and the login panel.
## Measuring FCP/LCP
Build once per revision and serve `dist/` (the Go SPA handler or any static
server that also answers `/api/*` for the auth check):
```bash
npm run build:web
```
Capture both metrics in a Playwright page with a fresh browser context:
```js
await page.addInitScript(() => {
window.__vitals = {};
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) window.__vitals.fcp = entry.startTime;
}).observe({ type: "paint", buffered: true });
new PerformanceObserver((list) => {
const entries = list.getEntries();
window.__vitals.lcp = entries[entries.length - 1].startTime;
}).observe({ type: "largest-contentful-paint", buffered: true });
});
await page.goto(origin, { waitUntil: "networkidle" });
const vitals = await page.evaluate(() => window.__vitals);
```
Run the same script against the base commit and this branch with the same
network/CPU throttling and the same auth fixture. The first screen for an
unauthenticated session must not request `icons-vendor`, the `Sidebar` chunk or
the annotation workspace stylesheet. For a returning session the `Sidebar`
chunk is warmed as soon as the shell paints, concurrently with `/api/auth/me`,
instead of after the route starts rendering.
## Verification commands
```bash
npm run lint:web
npm run test:frontend:gate
npm run build:web
```