
# The web

A Flutter app in a browser draws on a canvas inside an HTML page. The starter and its generator take care of that page and of what is around it. They write the title, description and colors into `web/index.html`, the page loader that shows while Flutter downloads, the fixes for apps' own browsers, the dev server of `flutter run`, and, when asked, a real HTML page per address for search engines. All of it comes from properties, read at build time by `spring_core_dart_generator`. This page lists every web feature, with a link to its own page.

## Why

A plain Flutter web build has a blank page while it downloads, a random port in development, no text for search engines or link previews, a page that closes on a swipe in an app's own browser, and a phone that draws nine times the pixels it needs. Each fix is a few lines of HTML or YAML that are easy to forget. Here they are properties, kept with the rest of the configuration in `application-web.yml`.

## Example

```yaml
# lib/resources/application-web.yml: only a browser reads it
spring:
  flutter:
    web:
      page:
        swipe-to-close: false     # apps' own browsers: a swipe scrolls
        max-pixel-ratio: 2        # phones' 3x screens drawn at 2x
        translate: false          # no translation offer that cannot work
      dev-server:
        port: 5050
        proxy:
          - prefix: /api/
            target: http://localhost:8080
      seo:
        enabled: true
        site-url: https://books.example.com
        from-routes: true
```

Run `dart run build_runner build`, then `flutter run -d chrome` or `flutter build web`.

## Everything at a glance

| Feature | What you get | Details |
|---|---|---|
| The page around the app | Title, description, colors, swipe-to-close, pixel ratio, translation | [below](#the-page-around-the-app) |
| The browser bar's color | `theme-color` from the theme, light and dark | [below](#the-browser-bars-color) |
| The page loader | The theme's splash in HTML while Flutter downloads | [The page loader](../spring-core-dart-generator/flutter/page-loader.md) |
| The dev server of `flutter run` | A fixed port, a proxy, headers, a Content Security Policy | [below](#the-dev-server-of-flutter-run) |
| Addresses | Paths without `#`, links to a `#heading` | [The web and deep links](../spring-boot-starter-flutter-navigation/web-and-deep-links.md) |
| Deep links | The `.well-known` files under `web/` | [Deep links](../spring-core-dart-generator/flutter/deep-links.md) |
| SEO | A real HTML page per address, a sitemap, link previews | [SEO](seo.md) |
| Fonts | A font per language, no fallback downloads | [below](#fonts) |
| Assets on demand | Pages and pictures downloaded only when read | [below](#files-downloaded-on-demand) |
| WebAssembly | `flutter build web --wasm` | [below](#webassembly) |
| Markdown placeholders | `{{key}}` in pages, from the configuration | [below](#values-in-pages) |
| The frame meter | Frames a second, in a release too | [below](#the-frame-meter-in-a-release) |
| The timeline | The start and every observation, in a release too | [The timeline](timeline.md) |
| Logins | The server logs in, or the browser does | [below](#logins-in-a-browser) |
| Hosting | Static hosts and `spring_boot_starter_web` | [below](#hosting) |
| The browser cache | `web/_headers` from `spring.web.resources.cache.cachecontrol.*`: the build's files asked for again, the assets kept | [The browser cache of a web build](cache-headers.md) |

## The page around the app

The generator writes these into `web/index.html` when `build_runner` runs:

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.app.title` | text | none | `<title>`, and `name` and `short_name` of `web/manifest.json` |
| `spring.flutter.app.description` | text | none | `<meta name="description">` and the manifest's `description` |
| `spring.flutter.web.page.swipe-to-close` | bool | `true` | `false` keeps the page open on a swipe down in apps' own browsers (a messenger's, a social app's); the swipe then scrolls the app |
| `spring.flutter.web.page.max-pixel-ratio` | number, 1 or more | the screen's own | The most pixels for each point Flutter draws at |
| `spring.flutter.web.page.translate` | bool | `true` | `false` writes `translate="no"` and `<meta name="google" content="notranslate">`, so browsers and Google do not offer to translate the page |

**Swipe to close.** A link opened in a messenger or a social app shows in the app's own browser. That browser closes the page on a swipe down when the page is at its top. A Flutter page always is (it scrolls inside its canvas), so every swipe down closes it. With `false`, on a touch screen, the page is made a thousand screens tall and scrolled to its end, with Flutter's view fixed. It is never at its top, so a swipe down is Flutter's.

**Pixel ratio.** A phone's screen has 3 pixels per point, so every frame is 9 times the pixels of the page, and its graphics chip drops frames on a full-screen scroll. `2` draws 2.25 times fewer, and the text stays sharp. A script in `web/index.html` sets it before the engine starts. A screen at or under the value is left as it is.

**Translation.** Flutter draws its text on a canvas, so a translator finds none. `false` removes an offer that cannot work. The SEO pages get the same attributes.

Every block and its markers: [The page's head and manifest](../spring-core-dart-generator/flutter/page-loader.md#the-pages-head-and-manifest).

## The browser bar's color

With a theme, the build writes its `primary` color as `<meta name="theme-color">` and its `surface` as the page's background and the manifest's `background_color`. A phone's browser paints its bar in that color. With `system` (a light and a dark theme), it writes two `theme-color` tags, one for `prefers-color-scheme: light` and one for `dark`, and a dark background too. The bar then matches the theme the visitor sees. See [Theme colors](themes/colors.md).

## The page loader

While the browser downloads Flutter, the page shows what the generator writes from the `splash` of the active theme: its background, logo, title and loader, in HTML and CSS. When the Flutter splash has painted, it takes over without a jump. See [The page loader](../spring-core-dart-generator/flutter/page-loader.md) for what is written, [Loaders and the splash](themes/loaders.md) for the theme's side, and [A web page loader that does not freeze](themes/loaders.md#a-web-page-loader-that-does-not-freeze) for animations that keep moving while the browser compiles the app.

## The dev server of flutter run

`flutter run -d chrome` serves the web version on a random port. That breaks whatever needs a fixed origin: the server's CORS list, the page an SSO login sends the browser back to. Since Flutter 3.38, `flutter run` reads its dev server's settings from `web_dev_config.yaml`, which the generator writes from these keys. It reads them as the app reads its configuration in a browser: `application.*`, then `application-web.*`, and the files of the profiles `spring.profiles.active` names there. `--dart-define` values do not count.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.web.dev-server.host` | text, not empty | any address | The address to listen on: `localhost`, or `0.0.0.0` for other devices on the LAN |
| `spring.flutter.web.dev-server.port` | 0 to 65535 | a free port | The port; a port browsers refuse to open (Chromium's blocked list) is a warning |
| `spring.flutter.web.dev-server.base-href` | path starting and ending with `/` | `/` | The path the app is served under (`/shop/`) |
| `spring.flutter.web.dev-server.https.cert-path` | file path | none (HTTP) | The TLS certificate (PEM); set it with `cert-key-path` |
| `spring.flutter.web.dev-server.https.cert-key-path` | file path | none | Its private key (PEM) |
| `spring.flutter.web.dev-server.headers.<Name>` | text | none | A header added to every response |
| `spring.flutter.web.dev-server.proxy[n].target` | absolute URL | none | Where requests matching rule `n` are forwarded; required in every rule |
| `spring.flutter.web.dev-server.proxy[n].prefix` | path | none | Rule `n` matches paths starting with it (`/api/`) |
| `spring.flutter.web.dev-server.proxy[n].regex` | regular expression | none | Or paths matching it; each rule sets exactly one of `prefix` and `regex` |
| `spring.flutter.web.dev-server.proxy[n].replace` | text | the path unchanged | The forwarded path: the matched part replaced, `$1` for a group |
| `spring.flutter.web.dev-server.content-security-policy` | text | none; a ready policy in the security starter's spa mode | The page's Content Security Policy header |
| `spring.flutter.web.dev-server.content-security-policy-report-only` | bool | `false` | Send the policy as `Content-Security-Policy-Report-Only`: violations are reported, nothing is blocked |
| `spring.flutter.web.dev-server.content-security-policy-connect-src` | list of origins | none | Origins added to the `connect-src` of spa mode's ready policy: the APIs the app calls |

The proxy is the simplest way to talk to your own server during development. With `/api/` forwarded to it, the page and the API have one origin: no CORS settings, and a session cookie is a first-party cookie, so a login with a session works in every browser.

The Content Security Policy runs development under the policy production sends. The ready policy of spa mode already allows what Flutter's engine needs and the hashes of the page's own scripts (the page loader, swipe-to-close, the pixel ratio). Hot reload breaks a strict policy, so turn on `content-security-policy-report-only` in a development profile when it gets in the way.

An invalid value fails the build, naming the key; a misspelled key is a warning. A `--web-port` or `--web-hostname` flag still wins. These settings are for `flutter run` only: `flutter build web` makes files for your own web server, which has its own settings. Every rule, the generated file and the ready policy: [The web dev server](../spring-core-dart-generator/flutter/web-dev-server.md).

## Addresses in the browser bar

With [spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md), the address bar shows the route as a path (`/catalog/books/1`), not after a `#`. A link to `/docs/beans#bean-methods` opens the page scrolled to that heading, on the first load too. The host must answer every address of the app with a page; see [Addresses in a browser](../spring-boot-starter-flutter-navigation/web-and-deep-links.md#addresses-in-a-browser).

## Deep links

The same addresses can open the mobile app. For a web app, the generator writes `apple-app-site-association` and `assetlinks.json` into `web/.well-known/`, so the site serves them with the app. See [The web and deep links](../spring-boot-starter-flutter-navigation/web-and-deep-links.md#deep-links) and [Deep links](../spring-core-dart-generator/flutter/deep-links.md).

## SEO

Search engines and link previews do not run the app, so they see an empty page. With `spring.flutter.web.seo.enabled`, the build writes a real HTML page per address, with its title, description, preview tags and text, plus `sitemap.xml`, `robots.txt`, `llms.txt` and a Markdown copy of each page. Step by step: [SEO](seo.md).

## Fonts

A font declared for one language (`spring.flutter.fonts.families.<family>.languages`) is downloaded only when the app shows that language. Named in the theme's `font-family-fallback`, it also stops the web engine from fetching its own fallback fonts, page after page, for characters the main font lacks. See [Assets and fonts](assets-and-fonts.md#fonts) and [A font for a language](themes/typography.md#a-font-for-a-language). For other characters, the [font warm-up](splash.md#fonts-for-the-apps-text) downloads what is needed behind the splash.

## Files downloaded on demand

By default every file of `lib/resources/` is embedded in the program, so the browser downloads all of them. `spring.resources.embed.exclude` leaves globs out (`content/**`, `images/**`): they become Flutter assets, and a browser downloads one only when the app reads it. On this site, that made `main.dart.wasm` 3.7 MB instead of 11.6 MB. `spring.resources.prefetch` downloads them all in one file after the app is shown, so every page then opens at once ([Downloading them together](../spring-core-dart-generator/resources.md#downloading-them-together)). The search reads its own index the same way, one file per language ([The index the build writes](../spring-search-dart/searching.md#the-index-the-build-writes)). See [Leaving files out of the binary](../spring-core-dart-generator/resources.md#leaving-files-out-of-the-binary). Any Flutter asset is also readable as `asset:path`; see [Assets and fonts](assets-and-fonts.md).

## WebAssembly

Build the app with `flutter build web --wasm`. Its Dart code then runs as WebAssembly, faster than the JavaScript build, and a browser without support gets the JavaScript build automatically. Every package an app can run in a browser compiles to Wasm, and CI checks it. More: [WebAssembly](../../docs/webassembly.md).

Flutter's loader runs the WebAssembly build only in Chrome and Edge unless told otherwise. `spring.flutter.web.page.wasm-allow-list` lets Firefox and Safari run it too:

```yaml
# lib/resources/application-web.yml
spring:
  flutter:
    web:
      page:
        wasm-allow-list:
          gecko: true     # Firefox 147 and newer
          webkit: true    # Safari 26.2 and newer
```

- **Not set:** nothing is written, and Flutter's own choice applies (Chrome and Edge only).
- **An older browser**, or one without the WebAssembly features the app needs, still gets the JavaScript build: Flutter's loader checks them first.
- **Your own `flutter_bootstrap.js`** that passes a `wasmAllowList` keeps its value for each browser it names.
- **A wrong name or value** (`opera`, `yes`) fails the build.

## Values in pages

With `spring.flutter.markdown.placeholders: true`, a `{{key}}` in a Markdown page shows the configuration's value. The SEO pages, their Markdown copies and `llms.txt` get the same values. See [Values from the configuration](markdown.md#values-from-the-configuration).

## The frame meter in a release

The frame meter shows the frames a second the app really draws. It can ship in a release build alone (`spring.flutter.debug.frame-meter.enabled`), so you can measure the real site on a real phone. Open it with ⌘⇧X, or five taps and a hold. See [The frame meter](frame-meter.md#in-a-release). The [timeline](timeline.md) (⌘⇧L) ships the same way and shows where the start's time goes; both share a corner through the [dock of the debug overlays](overlays.md).

## Logins in a browser

[spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md) reads `spring.flutter.security.web.*` in a browser. Either the server logs the user in ([server mode](../spring-boot-starter-flutter-security/web-server-mode.md)), or the browser does by itself ([spa mode](../spring-boot-starter-flutter-security/web-spa-mode.md), which also sets the ready Content Security Policy above).

## Hosting

`flutter build web` writes `build/web/`, plain files any static host serves. With SEO pages, choose `spring.flutter.web.seo.page-files` for your host: `html` for Cloudflare Pages, GitHub Pages and Netlify, which serve `<path>.html` at `<path>` with no redirect. See [Serving the pages](seo.md#serving-the-pages). To serve the build from your own Dart server, see [Static resources](../spring-boot-starter-web/static-resources.md) (`spa-fallback`, `directory-index`).

On Cloudflare Pages, how long browsers keep the files comes from `web/_headers`. With `spring.web.resources.cache.cachecontrol.*` set, every build writes a block of rules into it: `no-cache` for the page, `main.dart.js` and the other files without a hash, the configured `Cache-Control` for the app's assets. See [The browser cache of a web build](cache-headers.md).

## See also

- [SEO](seo.md)
- [The browser cache of a web build](cache-headers.md)
- [The generator for Flutter](../spring-core-dart-generator/flutter/index.md)
- [The splash and the start](splash.md)
- [Configuration in a Flutter app](configuration.md)
- [All properties](properties.md)
