88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# Frontend Asset Vendoring Playbook
|
|
|
|
This is the repeatable process used in GIA to self-host third-party frontend assets, pin versions, record provenance, and keep template SRI hashes maintainable.
|
|
|
|
## Goals
|
|
|
|
- Avoid runtime CDN dependencies for core UI assets.
|
|
- Pin exact upstream versions and package integrity in source control.
|
|
- Record provenance, license, and SRI for each third-party asset.
|
|
- Keep a simple manifest-driven workflow that can be copied into other projects.
|
|
|
|
## Files
|
|
|
|
- `tools/frontend_assets/package.json`
|
|
- Exact npm dependency pins for vendored frontend libraries.
|
|
- `tools/frontend_assets/package-lock.json`
|
|
- npm lockfile integrity and tarball resolution source of truth.
|
|
- `tools/frontend_assets/asset-manifest.json`
|
|
- Maps upstream package files and URL bundles into local `core/static/` targets.
|
|
- `scripts/vendor_frontend_assets.py`
|
|
- Copies npm assets, downloads non-npm bundles, computes local SHA-256 and SRI SHA-512, and emits inventory reports.
|
|
- `artifacts/frontend_libraries.md`
|
|
- Human-readable inventory with versions, licenses, official URLs, tarballs, upstream integrity, and local SHA/SRI.
|
|
- `artifacts/frontend_libraries.json`
|
|
- Machine-readable inventory for template updates and audits.
|
|
|
|
## Standard Workflow
|
|
|
|
1. Add or update exact versions in `tools/frontend_assets/package.json`.
|
|
2. Confirm each package is the official distribution, not a typosquat or community fork.
|
|
3. Update `tools/frontend_assets/asset-manifest.json` with the exact files to vendor.
|
|
4. Run `npm install --ignore-scripts` in `tools/frontend_assets/`.
|
|
5. Run `./genv/bin/python scripts/vendor_frontend_assets.py`.
|
|
6. Copy the emitted `sri_sha512` values into template tags in `core/templates/base.html`.
|
|
7. Restart the stack so `collectstatic` republishes the new files.
|
|
8. Verify in the browser that assets load from local static URLs with no CDN fallbacks.
|
|
|
|
## Provenance Rules
|
|
|
|
- Prefer official project docs or official extension listings before trusting npm search results.
|
|
- For Bulma extensions, treat `https://bulma.io/extensions/` as the discovery source and verify the linked package/repo matches the npm package name.
|
|
- Confirm npm metadata matches the expected project:
|
|
- homepage
|
|
- repository
|
|
- maintainers
|
|
- license
|
|
- publish recency
|
|
- Keep exact versions in `package.json`; do not use ranges.
|
|
- Use `package-lock.json` as the immutable record of tarball URLs and upstream integrity.
|
|
- If a library is not safely available from npm, vendor it from the official upstream URL as a `url_bundle`.
|
|
- Do not silently substitute a “free” or differently-scoped package if the templates rely on another asset family.
|
|
|
|
## GIA Decisions
|
|
|
|
- Font Awesome:
|
|
- GIA templates use icon classes that are not safely replaceable with `@fortawesome/fontawesome-free`.
|
|
- The existing Font Awesome Pro `site-assets` v6.1.1 bundle is self-hosted under `core/static/vendor/fontawesome/` instead.
|
|
- jQuery:
|
|
- Latest npm is 4.x, but GIA stays on `3.7.1` to avoid breaking older plugins.
|
|
- Bulma extensions:
|
|
- `bulma-calendar`, `bulma-tagsinput`, `bulma-switch`, `bulma-slider`, and `bulma-tooltip` were matched against Bulma's official extensions page before pinning.
|
|
- `bulma-calendar` and `bulma-tooltip` are deprecated on npm, but Bulma still points to the Wikiki ecosystem for these extensions, so they were kept and documented instead of replaced ad hoc.
|
|
|
|
## Theme Strategy
|
|
|
|
- `core/static/css/gia-theme.css` is now the project override layer instead of an inline `<style>` block in `base.html`.
|
|
- This is the low-friction step that works with the current stack immediately.
|
|
- If we want a true Bulma theme build later, add `sass` to `tools/frontend_assets`, create a `gia-bulma.scss` entrypoint that sets Bulma theme variables before importing Bulma, and vendor the compiled output through the same manifest process.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
cd /code/xf/GIA/tools/frontend_assets
|
|
npm install --ignore-scripts
|
|
|
|
cd /code/xf/GIA
|
|
./genv/bin/python scripts/vendor_frontend_assets.py
|
|
bash ./scripts/quadlet/manage.sh restart
|
|
./genv/bin/python manage.py check
|
|
```
|
|
|
|
## Verification Checklist
|
|
|
|
- `core/templates/base.html` only references local static URLs for vendored libraries.
|
|
- Each included stylesheet/script in `base.html` has an `integrity="sha512-..."` attribute.
|
|
- Browser network panel shows local asset hits and no unexpected CDN requests.
|
|
- `artifacts/frontend_libraries.md` reflects the exact deployed asset set.
|