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

3.2 KiB

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):

npm run build:web

Capture both metrics in a Playwright page with a fresh browser context:

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

npm run lint:web
npm run test:frontend:gate
npm run build:web