Skip to content

Vendored Assets

Jump to bottom
Copilot edited this page Jul 11, 2026 · 1 revision

Vendored Assets

The admin dashboard (src/admin_api/static/) has no CDN dependency for its own JS/CSS - htmx.min.js, bootstrap.min.css, bootstrap.bundle.min.js, and bootstrap-icons.svg are vendored directly in the repo and served by the Lambda itself, rather than fetched from a CDN at request time.

File Version License
htmx.min.js 2.0.9 (latest stable; 4.0.0-beta exists but isn't a stable release) BSD-2-Clause
bootstrap.min.css, bootstrap.bundle.min.js 5.3.8 MIT
bootstrap-icons.svg 1.13.1 (full sprite, ~1.1MB - browser-cached after first load via Cache-Control, not fetched per-request) MIT

There's no build step or package.json managing these - they're plain downloaded files, committed as-is.

Why vendor instead of using a CDN

  • Reliability: the dashboard doesn't depend on a third-party CDN's uptime to render at all - if the CDN is down or blocked (some corporate networks block common CDN hosts), the dashboard still works.
  • Privacy/security: no third-party host sees requests from every dashboard page load.
  • Consistency with the project's broader philosophy: this project avoids adding new external dependencies/services where a simpler, self-contained option exists (see the "No new AWS service" invariant in AGENTS.md for the AWS-side equivalent of this same instinct).

The one deliberate exception: Cloudflare Turnstile

The public contact-form integration (integration-snippet/nmailx-contact-form.js + example.html) loads Cloudflare Turnstile's client widget script live from Cloudflare's edge (https://challenges.cloudflare.com/turnstile/v0/api.js). This is not vendored, on purpose: Turnstile is a live challenge/attestation service, not a static library - vendoring a stale copy of it would break the challenge mechanism entirely. This lives on the customer's static site (the one embedding the contact form), not the admin dashboard itself, so it doesn't conflict with the "no CDN dependency" rule above, which is about the dashboard's own assets.

Bumping a vendored version

There's no automation for this - re-download the new version and replace the file in src/admin_api/static/:

curl -L -o src/admin_api/static/htmx.min.js \
  https://unpkg.com/htmx.org@<new-version>/dist/htmx.min.js

(similarly for the Bootstrap files and icon sprite from their respective release pages). Update the version table above and this wiki page, and re-run make check to confirm nothing in the dashboard's Python tests depends on file contents changing (they shouldn't - these are static assets, not something the test suite inspects).

Related: this project's own landing page

The GitHub Pages marketing site at www.nmailx.com follows the same philosophy - docs/index.html is a single, hand-written, dependency-free HTML/CSS file with no external framework or CDN reference at all (not even a vendored one - it's simple enough not to need one). See GitHub Pages and DNS for how that page is deployed.

Clone this wiki locally