mirror of https://github.com/synctv-org/synctv
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
98 lines
3.2 KiB
Markdown
98 lines
3.2 KiB
Markdown
1 month ago
|
# 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:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
schema-version = 1
|
||
|
|
|
||
|
|
[source]
|
||
|
|
kind = "dist"
|
||
|
|
path = "../synctv-app/build/web"
|
||
|
|
```
|
||
|
|
|
||
|
|
Local Flutter project:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
schema-version = 1
|
||
|
|
|
||
|
|
[source]
|
||
|
|
kind = "local-project"
|
||
|
|
path = "../../flutter/synctv-app"
|
||
|
|
allow-dirty = true
|
||
|
|
```
|
||
|
|
|
||
|
|
Immutable Git checkout:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|