About
About
What a build ships
Learn what a build already does to be fast, see what it weighs, set budgets that warn, time pages in a browser, and avoid what makes a site slow.
This essay is about what wf build writes, and why a WebFluent site is fast by default rather than by effort.
Most slow sites are not slow because someone chose to make them slow. They are slow because every library, component and font arrived for a good reason, and nothing ever weighed the total. A framework cannot weigh it for you: it does not know which of its features your program uses, so it ships them all and leaves the pruning to a bundler that reads JavaScript it did not write.
A compiler that reads the whole program can do better. It knows which runtime modules the code it generated calls, which built-ins' rules the pages use, and which design tokens something names, so a build ships those and nothing else. Your part is smaller: look at what it writes, set a limit that warns you when it grows, and avoid the few patterns no compiler can fix.
What the build already does
You get these without setting anything:
- Only the runtime you use. The runtime is the JavaScript the compiled pages call. It is a set of modules, and a build keeps only the ones its code reaches, and of those only the functions its calls reach. A build of one page of static text, with no
app(so no router), is anapp.jsof about 5 kB, 1.9 kB gzipped; anappwith aRouteradds the router, about 4 kB gzipped more. - Short names. A minified build shortens the runtime's own names, its top-level ones and each function's locals. What your pages call keeps its name.
- A chunk per page.
build.split(on by default) writes each page's code and styles as their own files, loaded the first time its route is shown. A site of one page is not split: its code is all inapp.js. - Pre-rendered HTML. With
build.ssg, each page's HTML is written at build time, so the first paint needs no script. - One pruned stylesheet. It holds the rules of only the built-ins you use, and only the design tokens something names.
- Precompressed files. A
.gzfile sits beside every text file, for a host that serves it.wf servesends the same bytes, so Lighthouse run against the dev server measures what a deploy sends. - Images at every width, with
widthandheightso nothing shifts, a placeholder while they load, the first image eager and the rest lazy (Add a picture). - Minified output.
build.minify(on by default) strips comments and white space.
See what a build weighs
To see the size of everything a build writes, run the build with --stats:
$ wf build --stats
This is the output for the project wf init -t spa makes, measured with 7.0.0 and trimmed (the exact numbers move a little from release to release):
What it weighs
app.js 69.0 kB (22.8 kB gzipped)
styles.css 30.7 kB (5.8 kB gzipped)
pages/Settings.js 9.0 kB (2.2 kB gzipped)
pages/Profile.js 5.6 kB (1.5 kB gzipped)
pages/Tasks.js 4.2 kB (1.3 kB gzipped)
pages/Home.js 3.5 kB (1.1 kB gzipped)
…
total 123.7 kB
Runtime: 24 of 58 modules, 171.5 kB of 596.5 kB kept, 153.9 kB with its names shortened (before minifying)
core 27.6 kB always
layer 19.6 kB needed by drawer
form 16.4 kB WF.form
router 14.4 kB WF.router
motion 12.6 kB enter:
each 10.6 kB WF.each
store 9.9 kB WF.store
keep 9.6 kB WF.persist
…
field 2.7 kB WF.field
…
left out: format offline peer scalars text slot browser host …
Tokens: 33 nothing in the output names, left out
Read it in three parts:
- What it weighs lists every text file with its gzipped size. The starter's form brings in
formandfield, its store brings instoreandkeep, its second page brings inrouter, and its entry animations bring inmotion. - Runtime lists each module with what the build kept of it — the functions the program reaches — and what reached it. When a module you did not expect is in the build, look here first.
- Tokens counts the design tokens the build left out because nothing names them.
Each build records its sizes in .wf-sizes.json beside the project, so the next --stats shows how each file moved since the last build (for example, +20 B).
The project's own scripts are listed by their path under js/, such as js/tilt.js (Call your own script). The build copies them as written: it does not minify a file it promises to ship byte for byte.
Set a size budget
To be warned when a file grows past a size, name its gzipped limit in build.budget:
{ "build": { "budget": { "app.js": "40 kB", "styles.css": "30 kB", "pages/Home.js": "10 kB" } } }
Any output may have a budget, including a page's chunk and one of your own scripts under js/. A build over budget prints a warning and goes on. A CI job that should fail on it can read the same numbers.
Time pages in a browser
To measure how fast each page paints, build the site and run wf verify with a budget in milliseconds:
$ wf build && wf verify --budget 800
wf verify loads every route in headless Chrome. For each route it prints the first contentful paint, the number of nodes in the document, and the bytes and requests it took. --budget 800 fails a route whose first paint is slower than 800 ms. Lighthouse and the browser's performance panel work on the build as on any other site.
Avoid what makes a site slow
These are the patterns that slow a WebFluent site down, and what to do instead:
| Pattern | Why it is slow | Do this instead |
|---|---|---|
|
A large |
|
Keep build-time data to what pages show. Ask for the rest with a |
| A waterfall of requests | A resource whose URL depends on another's answer waits for that answer | Ask for both at once, or have the server send them together |
|
Layout decided by |
|
Use responsive values, which are CSS |
|
|
It ships every module |
Use it only when a hand-written script calls |
| Web fonts | Each weight is a download |
Use |
| An unkeyed list that changes |
|
Key it: |
| Pictures the build cannot process | An SVG, a URL or a path built at run time is used as written: one size, no placeholder |
Use a literal |