Review application A.3.4
Frontend asset management
On this page
The web app serves every third-party browser library from static/vendor/ instead of loading it from a public CDN, so a page contacts no third-party domain for code and keeps working when a CDN is blocked or down. The exact versions are set in package.json, and every change to a vendored file shows in Git. This page explains which files are copied, how they are trimmed and how to update a library.
Vendored libraries
npm installs the libraries; the sync script scripts/sync_vendor_assets.mjs copies the files the app needs into static/vendor/:
| Library | Version | What is copied | Used by |
|---|---|---|---|
| Bootstrap | 5.3.3 | bootstrap.min.css, bootstrap.bundle.min.js |
All pages (layout, modals, dropdowns) |
| Font Awesome | 5.15.3 | Merged all.min.css + solid/regular woff2 webfonts |
All pages (icons) |
| Leaflet | 1.9.4 | leaflet.css, leaflet.js, marker images |
Map pages (index, problems, routes) |
| Mermaid | 10.9.8 | mermaid.min.js |
Docs page only |
| Cytoscape.js | 3.34.3 | cytoscape.min.js |
Code quality dashboard only (module map) |
The versions in package.json (devDependencies) are authoritative. The sync script writes static/vendor/VERSIONS.json (a machine-readable list of the vendored versions), and the entire static/vendor/ directory is committed to the repository.
Templates
Templates load the files with Flask's url_for('static', ...) or with paths below /static/vendor/:
| Template | Libraries loaded |
|---|---|
templates/layouts/base.html |
Bootstrap CSS/JS, Font Awesome CSS |
templates/layouts/map.html |
Leaflet CSS, for the map pages index.html, problems.html and routes.html |
templates/components/_map_scripts.html |
Leaflet JS, for the same pages |
templates/pages/docs.html |
Mermaid JS |
templates/pages/quality.html |
Cytoscape.js |
templates/reports/printable.html |
Bootstrap CSS, Font Awesome CSS |
PDF rendering caveat
PDF generation uses WeasyPrint with a file-system base_url, where absolute web paths such as /static/... do not resolve. Therefore:
templates/reports/printable.htmluses apdf_assets_prefixvariable (default:/static/vendor/).- PDF generation code passes
pdf_assets_prefix='static/vendor/'so WeasyPrint resolves local files relative to the repository root. - Affected call sites:
backend/blueprints/reports.pyandbackend/services/stats_export.py.
The sync script
scripts/sync_vendor_assets.mjs deletes the existing library folders under static/vendor/, copies the explicit list of distribution files from node_modules, merges and trims Font Awesome, and writes static/vendor/VERSIONS.json from package.json:
| Script | Command | Purpose |
|---|---|---|
vendor:sync |
node scripts/sync_vendor_assets.mjs |
Copy and optimise vendor assets (also available as the Sync vendor libraries task in .vscode/tasks.json) |
vendor:check-cdn |
node scripts/check_no_cdn_templates.mjs |
Fail if any template references an external CDN URL; run by scripts/run_quality.py (vendor-cdn check) in make quality-fast and CI |
Keeping the files small
General approach
- Only minified distribution files are copied (
*.min.js,*.min.css), exceptleaflet.css, which Leaflet ships unminified. - Only the files the application uses are copied, never whole library trees.
- The copy plan lists every file explicitly, without glob patterns; only one asset directory is copied whole, Leaflet's
images/.
Font Awesome trimming
The sync script trims Font Awesome while copying it:
- No brands: Only the
fas(solid) andfar(regular) icon styles are used. Brand icons and their webfonts are not copied. - woff2 only: Only the woff2 files of the two styles are copied; every modern browser supports the format. The eot, woff, ttf and svg fonts are not copied.
- Merged CSS: The upstream CSS files (
fontawesome.min.css,solid.min.css,regular.min.css) are merged into a singleall.min.csswhose@font-facerules name the woff2 files only.
What is copied unchanged
Bootstrap, Leaflet, Mermaid and Cytoscape.js are copied as their upstream distribution files, without CSS purging or custom builds, and the Font Awesome fonts keep all their glyphs.
What stays external
Only map tiles are loaded from other servers, because they are live imagery rather than static files: OpenStreetMap (tile.openstreetmap.org), the transport layer (tile.memomaps.de) and Esri World Imagery (server.arcgisonline.com). See A2.1.
Updating a library
- Update the version in
package.json. - Run
npm install. - Run
npm run vendor:sync. - Check the map pages, the documentation page, the code quality dashboard and the PDF reports by hand.
- Commit
package.json,package-lock.json, and the updatedstatic/vendor/files.
Code
| File | Role |
|---|---|
package.json |
The library versions and the vendor:sync and vendor:check-cdn scripts |
scripts/sync_vendor_assets.mjs |
Copies, trims and records the vendored files |
scripts/check_no_cdn_templates.mjs |
Fails when a template references a CDN |
static/vendor/VERSIONS.json |
The vendored versions, written by the sync script |
templates/reports/printable.html |
The pdf_assets_prefix that lets WeasyPrint find the vendored files |
Related pages
- A3.1 Dependencies and builds: how
package.jsonand the images fit together. - A2.1 Map data loading and rendering: the map tiles that stay external.
- A2.5 Reports and PDFs: the PDF exports that load the vendored files from disk.
- A4.4 Running the quality checks: the CI job that runs the CDN check.