Fast pages

On your computer, the Kladde is fast. It comes from localhost, with no network in between, and it consists of four small files. Anyone who opens it on an older phone on the train experiences something else; in lesson 2.1.5, throttling to “3G” already turned a few milliseconds into several seconds. And a real home page almost always has an image, often one straight from the camera, many megabytes in size.

In this lesson, you learn what makes a page slow, how to measure that without being fooled by a single number, and how to fix the most common causes. The Kladde’s home page gets an image along the way, first the way you often see it, then done right.

What makes a page slow

A page appears in steps. The browser requests the HTML and waits for the response. In it, it finds the stylesheet and the images and requests them. Only when the stylesheet has arrived does it draw the page for the first time, because without CSS it would look wrong. A stylesheet in the head is therefore blocking: Until it’s there, the page stays white. The causes that slow things down most often follow from that:

• Waiting time per request. Every request needs at least one trip to the server and back, the round trip time. On a mobile network, that’s quickly 100 milliseconds or more. Requests that can only begin after another one add up their waiting times.
• Bytes. A slow network transfers about 1.6 megabits per second, or roughly 200 kilobytes. A photo of 2.7 megabytes then needs about 14 seconds for the transfer alone.
• Images are the largest part of the bytes on almost every page, and they’re often much larger than they’re displayed.
• Fonts that have to be loaded before the text appears.
• Scripts that block drawing or keep the processor busy for a long time. The Kladde doesn’t have one yet; in module 2.2, you’ll see how a script doesn’t hold the page up.
• The server’s response time, until the first byte of the HTML arrives. That’s what it’s about from module 2.3 on.

The Core Web Vitals

How fast a page feels is described by three metrics, the Core Web Vitals:

For a page that many people visit, the thresholds apply to 75 percent of visits: Three out of four should be “good.” Such values from real visits are called field data. What you measure on your computer is lab data: a single load under fixed conditions. Lab data is good for comparing a change before and after. How real people fare, it shows only roughly.

INP exists only when someone does something with the page. A measurement that only loads measures the Total Blocking Time (TBT) instead: how long the processor was so busy during loading that the page couldn’t have responded to an input. A page without a script almost always has 0 here.

Measuring with Lighthouse

Lighthouse is built into the DevTools of Edge and Chrome. This is how you measure load time:

1. Open an InPrivate window (Ctrl+Shift+N) with the page. Extensions are usually off there, and nothing from the cache distorts the first visit.
2. Open the DevTools and in them Lighthouse (through the Command Menu if the tab is missing).
3. Choose Mode: Navigation, Device: Mobile and only the category Performance, then Analyze page load.

After a few seconds, a score from 0 to 100 appears at the top: red up to 49, orange up to 89, green from 90. Below it come the metrics and a list of hints on what can be improved. The score is a weighted average of five metrics: LCP, CLS and TBT count the most, plus First Contentful Paint (when anything appears at all) and Speed Index (how quickly the visible area fills up).

With “Mobile,” Lighthouse calculates as if a mid-range phone were loading over a slow 4G network: about 150 milliseconds of round trip time, 1.6 megabits per second and a processor four times slower than yours. Lighthouse doesn’t actually throttle in the process; it loads fast and calculates how long it would have taken under these conditions. The Performance tool next to it, by contrast, shows real, throttled loads: Set “Network throttling: Slow 4G” and “CPU throttling: 4x slowdown” there, reload, and the cards at the top show LCP, CLS and INP live. The numbers from the two tools differ; compare only measurements made with the same tool and the same settings.

One measurement is not yet a series

Measure the same page five times and you get five different results. The computer is sometimes more busy, sometimes less, an extension or a virus scanner injects scripts into every page, an update is downloading in the background. Four rules follow:

1. Measure several times, at least three, better five.
2. Take the median, the middle value, not the average and certainly not the best run. The median is insensitive to a single outlier.
3. Record the conditions: tool, device, throttling, window, what else was running. Only then can someone else repeat the measurement.
4. Change one thing at a time. If you change two things at once, you don’t know which one worked.

A difference of a few points between two runs is noise. A difference like the one in this lesson’s exercise, from 18 seconds to 1.5, is not.

Images

In the size they’re displayed

A photo from the camera is 4,000 pixels wide. On the Kladde’s home page, it’s 380 CSS pixels wide on a phone and at most 928 on the screen, as wide as the content of main. If the screen has a higher pixel density (device pixel ratio, DPR for short), it needs more real pixels: A phone with a DPR of 2 shows 380 CSS pixels with 760 real pixels. More than that doesn’t help; the browser scales the image down anyway, and the remaining bytes were transferred for nothing.

In a fitting format

srcset and sizes: the browser chooses

With srcset, you offer several sizes of the same image; with sizes, you say how wide it will be on the page. From that, the browser works out with its pixel density which file it needs:

<img class="office-picture" src="images/office-960.webp"
     srcset="images/office-960.webp 960w, images/office-1920.webp 1920w"
     sizes="(min-width: 60rem) 58rem, calc(100vw - 2rem)"
     width="960" height="640" alt="">

• 960w means: this file is 960 pixels wide.
• sizes means: from a window of 60rem on, the image is 58rem wide; below that, as wide as the window minus the two paddings of main. That’s the same calculation as in the stylesheet, only written down for the browser, which has to choose the file before the stylesheet has arrived.
• src applies to browsers that don’t know srcset.

Which file the browser took is revealed by the console: Select the image in Elements and type $0.currentSrc.

width and height against shifting

If an image loads without dimensions, the browser doesn’t know how tall it will be. It draws the page first without the image, and when the image arrives, it pushes everything below it down. Anyone who was just about to read or tap a link loses their place or misses. That’s what CLS measures.

With width and height in the HTML, the browser knows the aspect ratio from the start and keeps the space free. Together with the rule img { max-width: 100%; height: auto; } from lesson 2.1.4, the image is still as wide as the space; the attributes don’t set the displayed size, only the ratio. With several files in srcset, use the dimensions of one of them, because they all have the same ratio.

loading="lazy" only below the fold

loading="lazy" loads an image only when it comes near the visible area. For images far down a long page, that saves many bytes. For an image you see immediately, it does harm: The browser requests it only after it has laid out the page, instead of right when reading the HTML. If this image is the largest element, LCP gets later, and if the dimensions are missing, the page also shifts. The rule is simple: What you see without scrolling doesn’t get lazy.

Shrinking images with image.cs

For the exercises, you need an image in photo size and a tool for shrinking. The following program can do both. It draws a desk with a laptop, a Kladde, a cup and a plant and gives it the grain of a photo so that the file gets as heavy as one. It can shrink any image. It uses SkiaSharp, a graphics library from the .NET Foundation under the MIT license. Create image.cs in k2-practice:

// image.cs: draws a photo-sized image and shrinks images for the web
#:package SkiaSharp@4.155.0
#:package SkiaSharp.NativeAssets.Linux.NoDependencies@4.155.0

using SkiaSharp;

if (args.Length == 2 && args[0] == "photo")
{
    using SKBitmap photo = Draw(4000, 2667);
    Save(photo, args[1], SKEncodedImageFormat.Jpeg, 92);
    return 0;
}

if (args.Length >= 3 && args[0] == "resize")
{
    using SKBitmap original = SKBitmap.Decode(args[1]) ?? throw new InvalidOperationException($"Not an image: {args[1]}");
    foreach (string width in args[2..])
    {
        int w = int.Parse(width);
        int h = (int)Math.Round(original.Height * (double)w / original.Width);
        using SKBitmap smaller = original.Resize(new SKImageInfo(w, h), new SKSamplingOptions(SKCubicResampler.Mitchell))
            ?? throw new InvalidOperationException($"Resizing to {w} pixels failed.");
        Save(smaller, $"{Path.GetFileNameWithoutExtension(args[1])}-{w}.webp", SKEncodedImageFormat.Webp, 75);
    }

    return 0;
}

Console.WriteLine("Usage: dotnet run image.cs -- photo <file.jpg>");
Console.WriteLine("       dotnet run image.cs -- resize <file> <width> [<width> …]");
return 2;

static void Save(SKBitmap bitmap, string path, SKEncodedImageFormat format, int quality)
{
    using SKImage image = SKImage.FromBitmap(bitmap);
    using SKData data = image.Encode(format, quality);
    File.WriteAllBytes(path, data.ToArray());
    Console.WriteLine($"{path}: {bitmap.Width} × {bitmap.Height} pixels, {data.Size / 1024} KB");
}

// A drawn desk with a laptop, a Kladde, a cup and a plant, plus grain like a photo's.
static SKBitmap Draw(int width, int height)
{
    var bitmap = new SKBitmap(width, height);
    using var canvas = new SKCanvas(bitmap);
    float u = width / 100f;

    using var paint = new SKPaint { IsAntialias = true };
    paint.Shader = SKShader.CreateLinearGradient(new SKPoint(0, 0), new SKPoint(0, height),
        [new SKColor(0xf4, 0xef, 0xe6), new SKColor(0xd9, 0xd2, 0xc4)], SKShaderTileMode.Clamp);
    canvas.DrawRect(0, 0, width, height, paint);
    paint.Shader = null;

    paint.Color = new SKColor(0x8a, 0x5a, 0x3b);
    canvas.DrawRect(0, 57 * u, width, height, paint);

    paint.Color = new SKColor(0x2b, 0x31, 0x30);
    canvas.DrawRoundRect(18 * u, 30 * u, 34 * u, 24 * u, u, u, paint);
    paint.Color = new SKColor(0x8c, 0xc4, 0xf0);
    canvas.DrawRect(20 * u, 32 * u, 30 * u, 20 * u, paint);
    paint.Color = new SKColor(0x3d, 0x4a, 0x47);
    canvas.DrawRoundRect(14 * u, 54 * u, 42 * u, 3 * u, u, u, paint);

    paint.Color = new SKColor(0x1f, 0x5f, 0x5b);
    canvas.DrawRoundRect(60 * u, 45 * u, 18 * u, 12 * u, u / 2, u / 2, paint);
    paint.Color = new SKColor(0xf4, 0xef, 0xe6);
    canvas.DrawRect(62 * u, 45 * u, u, 12 * u, paint);
    for (int line = 0; line < 3; line++)
    {
        canvas.DrawRect(65 * u, (48 + 3 * line) * u, (line == 2 ? 6 : 10) * u, 0.8f * u, paint);
    }

    paint.Color = new SKColor(0xa4, 0x26, 0x2c);
    canvas.DrawRoundRect(81 * u, 49 * u, 6 * u, 8 * u, u, u, paint);

    paint.Color = new SKColor(0x2e, 0x7d, 0x4f);
    canvas.DrawCircle(93 * u, 33 * u, 5 * u, paint);
    canvas.DrawCircle(90 * u, 39 * u, 4 * u, paint);
    canvas.DrawCircle(96 * u, 40 * u, 4 * u, paint);
    paint.Color = new SKColor(0x6b, 0x3f, 0x2a);
    canvas.DrawRect(90 * u, 47 * u, 6 * u, 10 * u, paint);

    // Grain: every color value of every pixel is randomly made a little lighter or darker; the fourth byte is the opacity.
    canvas.Flush();
    using SKPixmap pixmap = bitmap.PeekPixels();
    Span<byte> bytes = pixmap.GetPixelSpan<byte>();
    var random = new Random(7);
    for (int i = 0; i < bytes.Length; i++)
    {
        if (i % 4 != 3)
        {
            bytes[i] = (byte)Math.Clamp(bytes[i] + random.Next(-12, 13), 0, 255);
        }
    }

    return bitmap;
}

The second #:package line brings the parts of SkiaSharp for Linux, for the codespace, for example; on Windows and macOS, they’re already included in the first package. random.Next(-12, 13) returns a whole number from −12 to 12; the upper bound isn’t included. Because Random starts with the fixed number 7, you get the same image on every run.

dotnet run image.cs -- photo office.jpg
dotnet run image.cs -- resize office.jpg 960 1920

office.jpg: 4000 × 2667 pixels, 2749 KB
office-960.webp: 960 × 640 pixels, 14 KB
office-1920.webp: 1920 × 1280 pixels, 43 KB

Your sizes may differ by a few kilobytes. The 960-pixel version has less than a hundredth of the original’s bytes: about a seventeenth of the pixels, and WebP packs them more densely than JPEG. In addition, shrinking smooths out the grain that makes the original so heavy.

Fonts

The Kladde writes with the system’s fonts (system-ui, “Segoe UI,” Roboto). That costs not a single request. A web font of your own is one file per style: regular, bold, italic, each separately. If you need one:

• only the styles the page really uses, in the WOFF2 format;
• font-display: swap in the @font-face rule, so the text appears immediately in a fallback font instead of waiting invisibly;
• serve the files yourself, from wwwroot. Then no request goes to a third-party server when the page loads, and with it goes no visitor’s address.

A switch from the fallback font to the web font can make text shift that runs wider in the new font. That counts in CLS, too.

Caching

What the browser already has, it doesn’t have to fetch again. How long it may keep something is stated by the server with the Cache-Control header:

You know the asking from lesson 2.1.5: The browser sends the ETag of its version in If-None-Match, and if the file is unchanged, the server answers with 304 and no content. That saves the bytes, but not the request’s waiting time.

The usual division follows from that:

• HTML gets no-cache. If a page changes, everyone should see the new one immediately.
• Stylesheets, scripts and images with a fingerprint in the name, such as kladde.6vlgbbyfj1.css, get a max-age of one year and immutable. If the content changes, the name changes, and the HTML points to the new file. The old one may sit in the cache forever; nobody asks for it anymore.

UseStaticFiles, which the Kladde has used since lesson 2.1.6, sends an ETag and Last-Modified, but no Cache-Control. Then the browser may estimate for itself how long a file is fresh, and that’s why kladde.css sometimes didn’t reach the server at all in lesson 2.1.5. MapStaticAssets is better. It serves the files from wwwroot as endpoints, with an ETag from the file’s content and with Cache-Control: no-cache for names without a fingerprint. The names with a fingerprint and immutable you get in module 2.5: Blazor puts them into the pages with @Assets["…"]. A static HTML file can’t do that.

Compression

Text packs well, often down to a quarter. The browser says in Accept-Encoding which methods it knows, usually gzip and br (Brotli, which packs a bit smaller still). The server answers with Content-Encoding and the packed content, plus Vary: Accept-Encoding, so that no intermediate cache hands the packed version to a browser that doesn’t understand it. Images in JPEG, WebP or PNG and fonts in WOFF2 are already packed; a second time brings nothing.

MapStaticAssets packs at build time, not on every request: with gzip in the ordinary build, and additionally with Brotli when publishing with dotnet publish. The packed files sit next to the originals, and the server picks the fitting one per request. One line is added to Program.cs:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseDefaultFiles();
app.UseStaticFiles();
app.MapStaticAssets();

app.Run();

Why do UseDefaultFiles and UseStaticFiles stay? MapStaticAssets knows only the files themselves, not default documents. The address / is therefore still rewritten by UseDefaultFiles to /index.html, and UseStaticFiles serves it. Everything else, including /index.html through the navigation’s links, comes from MapStaticAssets. That’s also how it stands in Microsoft’s documentation on Microsoft Learn; what exactly the order of the lines means, you’ll learn in module 2.3.

Measure compression on the published version. With dotnet run in the Development environment, Content-Encoding: gzip is in the header, but MapStaticAssets repacks changed files there at runtime and hardly smaller. Measured for this lesson: kladde.css came there at 4,760 bytes instead of 4,727, with 33 bytes more of packaging.

<img class="office-picture" src="images/office.jpg" alt="" loading="lazy">

.office-picture {
  display: block;
  margin-block: var(--space-4);
  border-radius: var(--radius);
}

<img class="office-picture" src="images/office-960.webp"
     srcset="images/office-960.webp 960w, images/office-1920.webp 1920w"
     sizes="(min-width: 60rem) 58rem, calc(100vw - 2rem)"
     width="960" height="640" alt="">

# Load times of the Kladde

The home page is measured in Edge, InPrivate window, Lighthouse:
Navigation, Mobile, Performance only, default settings. Three runs per state,
the median counts. Device: <computer>, otherwise running: <nothing / what>.

## Image on the home page
Before: office.jpg, 4000 × 2667 pixels, 2749 KB, without width and height, loading="lazy".
After: office-960.webp and office-1920.webp with srcset and sizes, width and height,
without lazy.

| State  | Score (3 runs)   | LCP (3 runs)     | CLS (3 runs)     | TBT | Median LCP | Median CLS |
| ------ | ---------------- | ---------------- | ---------------- | --- | ---------- | ---------- |
| before | …, …, …          | … s, … s, … s    | …, …, …          | …   | … s        | …          |
| after  | …, …, …          | … s, … s, … s    | …, …, …          | …   | … s        | …          |

HTTP/1.1 200 OK
Content-Length: 1052
Content-Type: text/css
Accept-Ranges: bytes
Cache-Control: no-cache
Content-Encoding: br
ETag: "9lG2FpBDT4u7bG8MDW5X2osGL0BCd3hB1y6YXImC34Q="
Last-Modified: <date and time of the build>
Vary: Accept-Encoding

The Kladde: an image with dimensions, measurements in docs

On the branch home-picture, these have now been added: the two WebP files in wwwroot/images, the image in index.html, the rule .office-picture in _layout.scss, MapStaticAssets in Program.cs and docs/load-times.md. Check with git status that neither office.jpg nor publish/ is included, and go through the definition of done, including the keyboard check and FastPass from lesson 2.1.7: The new image must be silent for screen readers. Commit with a message like “Add the office picture in the right size and serve compressed assets” and open a pull request with both series of measurements in the description.

That completes the prototype: three pages and an error page, semantic HTML, SCSS in the build, for phone and screen, checked against WCAG 2.2 AA and measured to be fast. In module 2.2, the contact list gets its first script.

What you can do now

• You explain why a page is slow: waiting time per request, bytes, blocking files, images and fonts.
• You know LCP, CLS and INP with their thresholds and tell lab data from field data.
• You measure with Lighthouse and the Performance tool several times under fixed conditions and summarize the runs with the median.
• You deliver images in a fitting size and as WebP with srcset and sizes, with width and height and without lazy in the visible area.
• You read Cache-Control, ETag, Content-Encoding and Vary, let MapStaticAssets pack when publishing and measure on the published version.

Further reading

• Optimize website speed using Lighthouse: Lighthouse in Edge step by step, with a demo page.
• Performance tool: Analyze your website's performance: the live values for LCP, CLS and INP and the settings for throttling.
• Serve static files in ASP.NET Core apps: how MapStaticAssets packs, assigns fingerprints and sets headers, also together with default documents.
• Response compression in ASP.NET Core: compression for responses that don’t come from files.
• Web Vitals at web.dev: the metrics and their thresholds in detail.
• Responsive images at MDN: srcset, sizes and picture in detail.