synctv/synctv-web-ui/README.md

SyncTV Web UI assets

This crate owns the acquisition, optional Flutter build, compression, manifest, and compile-time embedding of the SyncTV browser client. synctv-api-http only serves the generated asset table.

Sources

web-ui.toml reads prebuilt files from dist/. The directory is empty in Git apart from .gitkeep; place a Web distribution there before enabling the server's web-ui feature.

web-ui.production.toml is the versioned production source used by CI. Its Git source pins both the requested revision and its expected full lowercase commit SHA. The build fails when the revision resolves to another commit.

For local development, create the ignored web-ui.local.toml beside the default file. It takes precedence unless SYNCTV_WEB_CONFIG names another configuration. Relative paths resolve from the selected configuration file.

Prebuilt distribution:

schema-version = 1

[source]
kind = "dist"
path = "../synctv-app/build/web"

Local Flutter project:

schema-version = 1

[source]
kind = "local-project"
path = "../../flutter/synctv-app"
allow-dirty = true

Immutable Git checkout:

schema-version = 1

[source]
kind = "git"
repository = "https://github.com/synctv-org/synctv-app.git"
revision = "refs/tags/v1.2.3"
commit = "0123456789abcdef0123456789abcdef01234567"

The optional [build] table accepts flutter, arguments, and a dart-defines mapping. Arguments and defines participate in the build fingerprint.

Commands

Build and export the Web distribution:

SYNCTV_WEB_CONFIG=synctv-web-ui/web-ui.production.toml \
  make web-ui-build WEB_UI_EXPORT_DIR=synctv-web-ui/dist

Build the release server with the assets embedded:

make web-release-build

The Web-only command exports to target/web-ui-dist by default. CI uploads the exported distribution once, then passes its authenticated artifact URL and SHA-256 digest to the existing multi-platform Docker build. Docker verifies and embeds the archive; it never installs Flutter or builds the frontend.

Build controls

Variable	Behavior
SYNCTV_WEB_CONFIG	Select a configuration file explicitly.
SYNCTV_WEB_DIST	Use a prebuilt directory. This compatibility override takes precedence over configured sources.
SYNCTV_WEB_CACHE_DIR	Select the Git, Flutter output, and compression cache root.
SYNCTV_WEB_EXPORT_DIR	Copy the final uncompressed distribution to a disjoint directory.
SYNCTV_WEB_OFFLINE	Disable Git fetches and use flutter pub get --offline. Missing cache entries fail.
SYNCTV_WEB_FORCE_REBUILD	Fetch the pinned revision again and rebuild Flutter output.

Relative paths in these controls resolve from the workspace root containing the synctv-web-ui crate. Paths inside a selected configuration resolve from that configuration file.

The fingerprint includes the source file hash or pinned commit, Flutter version, build arguments, dart-defines, builder version, and final distribution hash. Git checkout, Flutter output, and compression data use separate cache layers. Ordinary workspace builds do not enable the embed feature and require no Flutter installation, Git access, or network access.