Fast first screen: login page and first paint (#3298)¶
The app draws each page with JavaScript, so a visitor sees nothing until
the bundle runs. This plan covers the first screen. Part 1 is the login
page and is built on the branch perf/first-screen, on top of #3244.
Part 2 is the first page of a signed-in user and is not started.
The record of each idea that was explored, with its numbers, is in 3298-first-screen-explorations.md.
Results of Part 1¶
Login page, local production build, Lighthouse mobile preset, median.
| Measure | #3244 branch | This branch |
|---|---|---|
| Lighthouse score | 86 | 100 |
| Largest paint, simulated | 4.21 s | 1.35 s |
| Login card complete, Slow 4G | 6.0 s | 4.4 s |
| Logo downloaded, Slow 4G | 6.0 s | 2.4 s |
| Requests | 63 | 30 |
| First-screen files, gzip | 327 KB | 235 KB |
| First-screen files, brotli | not served | 199 KB |
| Round trips before the card | 5 | 3 |
Signed-in pages keep their numbers: the home page paints at about 9 s and the results page at about 12 s on Slow 4G, before and after.
Decisions¶
- The login title paints from
index.html. A static element#shellshows only while#q-appis empty, so no script removes it. An inline script fills it on a/<lang>/loginURL only, in the language of the URL. The text comes fromsrc/i18n/login.tsthroughhtmlVariablesofquasar.config.js, so the text has one home. - A last boot file,
src/boot/first-frame.ts, waits two animation frames before the app mounts, 100 ms at most. Without it, a fast connection lets the app mount before the browser shows the first frame. The page then starts blank, and the largest paint is an element that the app draws. - The header and the two sidebars are not in the entry bundle.
src/router/authenticatedShell.tsloads them after a session exists and keeps the loaded components.MainLayout.vuerenders them as plain components. An async wrapper drew them one frame late and moved the page content (layout shift 0.389 on the results page). - The entry is two JavaScript files:
vendor(the libraries that each page needs) and the app entry. RolldowncodeSplitting.groupsmakes them. The chart and map libraries stay lazy. - The login page and the signed-in layout are each one
retryableImportofsrc/router/retryableImport.ts. All callers share one download. A failed download is forgotten, so the next navigation tries again. - Two events clear the static frame: a session call that says "signed in", and the reload prompt after a failed chunk. So a signed-in visitor of the login URL does not see the login title.
- If
/injectEnv.jsdoes not load,src/config/runtime.tsthrows and the static frame shows an alert in the language of the URL. - Quasar imports each boot file after the entry runs. A build plugin
adds one
modulepreloadlink for each boot chunk, so they download with the entry. - On a login URL, the app starts the login page import before the
session call answers, and
index.htmlpreloads the logo and the login illustration. - The reload prompt after a deploy is a notification with a "Reload" button and a "Later" button. The dialog plugin was its only user, and it cost 19 KB on each first load. The prompt no longer blocks the page behind it.
- The image holds a
.gzfile (gzip 9) and a.brfile (brotli 11) for each text file, made bybuild/precompress.mjsat build time. nginx has no brotli module: amaponAccept-Encodingand an internal location serve the.brfiles with the content type of the original.
First load, step by step¶
The diagram shows a first load of /en/login. The steps on the left of
the app run before Vue mounts. A dashed arrow is a download that starts
early and that a later step waits for.
sequenceDiagram
autonumber
participant B as Browser
participant H as index.html
participant A as App (router guards)
participant S as Server
B->>S: GET /en/login
S-->>B: index.html
H->>B: paint #shell with the login title
H-)S: preload logo.svg and login-illustration.svg
B->>S: entry, vendor, boot chunks, /injectEnv.js (parallel)
alt /injectEnv.js did not load
H->>B: #shell shows the alert, the app stops
end
A-)S: preload LoginPage chunk (loginPage.preload)
A->>S: GET /api/v1/session
alt not signed in
A->>A: await loginPage.get()
A->>B: mount the login page, #shell hides
else signed in
A->>B: clear #shell
A-)S: preload header, sidebars, home (authenticatedShell.preload)
A->>A: workspace guards, then await authenticatedShell.get()
A->>B: mount the home page with its header
end
alt a chunk fails
A->>B: clear #shell, show the reload prompt
end
Tests¶
tests/integration/login-shell.spec.ts: the first frame shows the title in both languages, stays empty on other pages, hides after the app mounts, and is the largest paint. It clears for a signed-in visitor and on a failed chunk, and shows the alert without/injectEnv.js.tests/unit/retryable-import.spec.ts: one shared download, a new download after a failure, and no unhandled rejection from a preload.tests/integration/authenticated-shell.spec.ts: the login page does not request the layout files, and the header is in the first frame of the page content.tests/integration/boot-chunks.spec.tsandlogin-parallel.spec.ts: the preload links and the parallel requests.tests/integration/chunk-load-reload.spec.ts: the reload prompt as a notification.docker/test-nginx.sh: 68 assertions on the real nginx image for the brotli and gzip negotiation.
On 2026-11-17 the branch passed 948 component tests and 139 e2e tests.
Part 2, not started¶
The signed-in home page waits for a chain: the session call, then the layout and page files, then the year configuration call, then the workspace call. The proposal, in this order:
- Run the year configuration call and the workspace call in parallel.
- Paint the header and the page frame before the data arrives.
- Start the session call from the HTML.
Caveats¶
- The first frame shows on a login URL only. A visitor who opens
/gets the redirect to login from the app, so/scores 91, not 100. - An institution with a taller logo can make the logo larger than the title. The first frame then loses the largest paint.
- The results page scores 80 in the mobile simulation, against 95 before. The real first paint did not change (11.6 s and 11.8 s on Slow 4G).
- Brotli is not confirmed behind the load balancer. The deployed chain passes gzip through unchanged (tested on dev on 2026-11-17).
- The local measurements use an HTTP/1.1 server. Production uses HTTP/2, so the wait of the session call behind the login files is smaller there.