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.

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

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.

See also