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
# 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 browser bar's color | theme-color from the theme, light and dark |
below |
| The page loader | The theme's splash in HTML while Flutter downloads | The page loader |
The dev server of flutter run |
A fixed port, a proxy, headers, a Content Security Policy | below |
| Addresses | Paths without #, links to a #heading |
The web and deep links |
| Deep links | The .well-known files under web/ |
Deep links |
| SEO | A real HTML page per address, a sitemap, link previews | SEO |
| Fonts | A font per language, no fallback downloads | below |
| Assets on demand | Pages and pictures downloaded only when read | below |
| WebAssembly | flutter build web --wasm |
below |
| Markdown placeholders | {{key}} in pages, from the configuration |
below |
| The frame meter | Frames a second, in a release too | below |
| The timeline | The start and every observation, in a release too | The timeline |
| Logins | The server logs in, or the browser does | below |
| Hosting | Static hosts and spring_boot_starter_web |
below |
| 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 |
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.
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.
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 for what is written, Loaders and the splash for the theme's side, and 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.
Addresses in the browser bar
With spring_boot_starter_flutter_navigation, 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.
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 and Deep links.
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.
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 and A font for a language. For other characters, the font warm-up 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). The search reads its own index the same way, one file per language (The index the build writes). See Leaving files out of the binary. Any Flutter asset is also readable as asset:path; see Assets and fonts.
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.
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:
# 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.jsthat passes awasmAllowListkeeps 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.
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. The timeline (⌘⇧L) ships the same way and shows where the start's time goes; both share a corner through the dock of the debug overlays.
Logins in a browser
spring_boot_starter_flutter_security reads spring.flutter.security.web.* in a browser. Either the server logs the user in (server mode), or the browser does by itself (spa mode, 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. To serve the build from your own Dart server, see Static resources (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.