Appearance
Asset Vendoring
The no-CDN policy, and the tooling that makes it maintainable.
The policy
AdminVora makes zero requests to any origin it does not control.
This applies to fonts, icons, JavaScript libraries, stylesheets, map tiles, images, and analytics. There are no exceptions in the shipped product.
Why
| Reason | Consequence of a CDN |
|---|---|
| CSP | Enterprise policies commonly forbid third-party origins entirely. script-src 'self' breaks any CDN script. |
| GDPR | German and Dutch courts have ruled that loading Google Fonts transmits IPs without consent. Fines have been issued. |
| Air-gapped deployments | Government, healthcare, and finance networks have no outbound internet. |
| Availability | A CDN outage takes your admin panel down with it. |
| Supply-chain attacks | Polyfill.io (2024) served malware to 100k+ sites through a domain sale. cdnjs/unpkg have no equivalent guarantee. |
| Unpublishing | left-pad (2016) proved a package can vanish from under you. |
| Performance | Cross-origin caching partitioning (all modern browsers) means a "shared" CDN cache no longer exists. A third-party origin now costs an extra DNS + TLS handshake for zero benefit. |
| Offline development | Working on a plane should not break your charts. |
How vendoring works
Third-party binaries are not committed. What is committed is a manifest describing exactly which files to copy from node_modules and their expected SHA-256 hashes.
node_modules/apexcharts/dist/apexcharts.esm.js
│
├─ tools/vendor-sync.mjs reads tools/vendor.manifest.json
├─ copies → src/vendor/apexcharts/apexcharts.esm.js
├─ computes SHA-256 → compares with the manifest
└─ aborts the build on any mismatchResult: the repository stays small, the build is reproducible, and a compromised or silently changed package is caught before it ships.
The manifest
jsonc
// tools/vendor.manifest.json
{
"$schema": "./vendor.schema.json",
"vendors": {
"apexcharts": {
"package": "apexcharts",
"version": "3.54.1",
"license": "MIT",
"homepage": "https://apexcharts.com",
"files": [
{
"from": "dist/apexcharts.esm.js",
"to": "apexcharts/apexcharts.esm.js",
"sha256": "9f3c1a2b7d5e4f8c0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6071"
},
{
"from": "dist/apexcharts.css",
"to": "apexcharts/apexcharts.css",
"sha256": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
"layer": "bootstrap"
}
],
"notes": "Chart theming is applied at runtime from CSS custom properties."
},
"tabulator-tables": {
"package": "tabulator-tables",
"version": "6.5.2",
"license": "MIT",
"files": [
{ "from": "dist/js/tabulator_esm.min.js", "to": "tabulator/tabulator.esm.min.js",
"sha256": "…" },
{ "from": "dist/css/tabulator.min.css", "to": "tabulator/tabulator.min.css",
"sha256": "…", "layer": "plugins" }
]
},
"quill": {
"package": "quill",
"version": "2.0.3",
"license": "BSD-3-Clause",
"files": [
{ "from": "dist/quill.js", "to": "quill/quill.js", "sha256": "…" },
{ "from": "dist/quill.snow.css", "to": "quill/quill.snow.css",
"sha256": "…", "layer": "plugins" }
]
}
}
}| Field | Purpose |
|---|---|
version | Must match package.json exactly; the tool verifies |
license | Aggregated into NOTICE.md at build time |
from / to | Source path inside the package → destination in src/vendor/ |
sha256 | Integrity check; a mismatch aborts the build |
layer | If present, the CSS is wrapped in @layer <name> on import |
provides | The bare specifier this file answers to, for a package other vendored files import |
rewriteImports | Rewrite this file's bare specifiers to relative paths on the way in |
subset | For fonts, the unicode ranges to retain |
provides / rewriteImports — a package tree with no single-file build
Most vendors ship one self-contained file. Some ship only UMD, and the loader reads the global back. CodeMirror 6 does neither: it is seventeen packages importing each other by bare specifier, which a browser cannot resolve without a node_modules it does not have.
Bundling would put a second, divergent build in front of files the demo pages link directly, and an import map would put seventeen entries in the <head> of every page that might one day carry an editor — a vendoring decision leaking into markup. So the specifier is rewritten on the way in, which is the same move as wrapping a stylesheet in its cascade layer: the vendored copy is a derivation of the pinned source, the derivation is declared here, and --audit re-derives it rather than trusting what is on disk. A hand-edited vendored file still fails.
json
"@codemirror/state": {
"package": "@codemirror/state",
"version": "6.7.1",
"files": [{
"from": "dist/index.js",
"to": "codemirror/state.js",
"provides": "@codemirror/state",
"rewriteImports": true,
"sha256": "…"
}]
}The assertion after the rewrite is the load-bearing half. Any specifier still unresolved when the pass finishes aborts the build, because a rewrite that silently misses one produces a file that looks vendored, passes its checksum, and fails in the browser the first time a customer opens the page. A version bump that gains a transitive dependency is exactly how that happens; it now stops at npm run vendor.
The sync tool
js
// tools/vendor-sync.mjs (abridged)
import { createHash } from 'node:crypto';
import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
import { dirname, join } from 'node:path';
const manifest = JSON.parse(readFileSync('tools/vendor.manifest.json', 'utf8'));
const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
const AUDIT = process.argv.includes('--audit');
const UPDATE = process.argv.includes('--update');
const sha = (buf) => createHash('sha256').update(buf).digest('hex');
let failures = 0;
for (const [name, v] of Object.entries(manifest.vendors)) {
// 1. Version pin must match the lockfile-installed version
const installed = JSON.parse(
readFileSync(`node_modules/${v.package}/package.json`, 'utf8')).version;
if (installed !== v.version) {
console.error(`✖ ${name}: manifest pins ${v.version}, installed ${installed}`);
failures++; continue;
}
for (const file of v.files) {
const src = join('node_modules', v.package, file.from);
const dest = join('src/vendor', file.to);
if (!existsSync(src)) {
console.error(`✖ ${name}: missing source ${src}`);
failures++; continue;
}
const buf = readFileSync(src);
const hash = sha(buf);
if (UPDATE) {
file.sha256 = hash;
} else if (file.sha256 !== hash) {
console.error(`✖ ${name}/${file.from} checksum mismatch`);
console.error(` expected ${file.sha256}`);
console.error(` actual ${hash}`);
console.error(` If this is an intentional upgrade, run: npm run vendor:update`);
failures++; continue;
}
if (AUDIT) continue;
mkdirSync(dirname(dest), { recursive: true });
writeFileSync(dest, buf);
}
}
if (UPDATE) writeFileSync('tools/vendor.manifest.json', JSON.stringify(manifest, null, 2) + '\n');
// Aggregate licences
if (!AUDIT && !failures) {
writeFileSync('NOTICE.md', renderNotice(manifest));
}
if (failures) { console.error(`\n${failures} vendor problem(s). Build aborted.`); process.exit(1); }
console.log(`✔ ${Object.keys(manifest.vendors).length} vendors verified`);Commands
bash
npm run vendor # copy + verify (part of npm run setup)
npm run vendor:audit # verify only — runs in CI, no writes
npm run vendor:update # recompute checksums after an intentional upgradeUpgrading a library
bash
npm install apexcharts@3.55.0
# edit tools/vendor.manifest.json → "version": "3.55.0"
npm run vendor:update
npm run test:visual # confirm nothing shifted
git add tools/vendor.manifest.json package.json package-lock.json
git commit -m "chore(vendor): apexcharts 3.54.1 → 3.55.0"The commit diff shows exactly which checksums changed — a reviewable supply-chain event rather than an invisible one.
Fonts
Fonts are vendored like any other package. @fontsource-variable/inter, @fontsource-variable/plus-jakarta-sans and @fontsource-variable/jetbrains-mono are pinned in package.json, and each woff2 file they ship is listed in tools/vendor.manifest.json with its checksum. npm run vendor copies them to src/vendor/fonts/<family>/ and reproduces their OFL licence in NOTICE.md.
No subsetting step runs here: Fontsource already splits each family by script. Every subset is vendored, and src/scss/base/_fonts.scss declares each one with the unicode-range from the package's own CSS, so a browser downloads only the subsets a page's text needs:
scss
// src/scss/base/_fonts.scss (one face of nineteen)
@layer base {
@font-face {
font-family: 'InterVariable';
font-style: normal;
font-weight: 100 900;
font-display: swap;
src: url('../vendor/fonts/inter/inter-latin-opsz-normal.woff2') format('woff2');
unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
}
}The url() is relative to the compiled stylesheet, which sits beside vendor/ in src/, dist/, html-dist/ and every starter kit. When you bump a font version, regenerate the rules from the package's opsz.css or wght.css, then run npm run vendor:update.
Vendor CSS and cascade layers
Vendor stylesheets are imported through SCSS so they land in the correct layer.
scss
// src/scss/vendor/_third-party.scss
@layer bootstrap {
@import '../../vendor/flatpickr/flatpickr.css';
@import '../../vendor/tom-select/tom-select.css';
@import '../../vendor/tabulator/tabulator.min.css';
@import '../../vendor/fullcalendar/main.css';
@import '../../vendor/quill/quill.snow.css';
@import '../../vendor/filepond/filepond.css';
@import '../../vendor/swiper/swiper.css';
@import '../../vendor/glightbox/glightbox.css';
@import '../../vendor/simplebar/simplebar.css';
@import '../../vendor/leaflet/leaflet.css';
}Then restyle in plugins/, which is a later layer:
scss
// src/scss/plugins/_flatpickr.scss
@layer plugins {
.flatpickr-calendar {
background: var(--av-surface-overlay);
border: 1px solid var(--av-border-subtle);
border-radius: var(--av-radius-lg);
box-shadow: var(--av-shadow-lg);
font-family: var(--av-font-sans);
}
.flatpickr-day {
border-radius: var(--av-radius-sm);
color: var(--av-text-primary);
&:hover { background: var(--av-surface-sunken); }
&.selected { background: var(--av-color-primary); color: var(--av-text-on-primary); }
&.today { border-color: var(--av-color-primary); }
&.flatpickr-disabled { color: var(--av-text-disabled); }
}
}No !important anywhere. Layers do the work.
The vendor directory and the asset base
The runtime is a classic script, and in a classic script a bare relative specifier resolves against the document, not against the file that wrote it. So the loader anchors every vendor path to the runtime's own URL and imports ../vendor/… from there — which is why dist/vendor/ has to stay a sibling of dist/js/, and why moving one without the other breaks the first chart on the page and nothing else.
Override the anchor when your asset pipeline hashes or relocates the runtime without moving vendor/ with it:
html
<script>window.__AV_ASSET_BASE__ = 'https://assets.example.com/adminvora/js/';</script>
<script src="https://assets.example.com/adminvora/js/adminvora.js" defer></script>The value is the directory the runtime is served from — the js/ folder, not the bundle root — because that is what ../vendor/ is resolved against. A missing trailing slash is added for you, since without one the last segment would be dropped and the vendors looked for one directory too high. This is the whole of it, in src/js/adminvora.js:
js
const override = typeof window.__AV_ASSET_BASE__ === 'string' && window.__AV_ASSET_BASE__
? window.__AV_ASSET_BASE__.replace(/\/?$/, '/')
: null;
const base = new URL(override || '.', document.currentScript?.src || location.href);window.__AV_ASSET_BASE__ is the only global AdminVora reads. tools/runtime-globals.mjs is the list, npm run check:globals fails the build if a name on it has no reader in src/js/ or if a document promises one that is not on it, and npm run test:asset-base proves the override from the path the server was actually asked for rather than from a value read back out of the page. That gate exists because this global shipped named across ten customer-facing documents while the loader never looked at it, so every reader who needed it set it and still got a 404.
Laravel Vite, Django's ManifestStaticFilesStorage, and Rails Propshaft all hash filenames — see the framework guides for the exact snippet each needs.
Subresource Integrity
SRI is unnecessary for same-origin assets and is not used by default, and build:dist generates no SRI manifest. If you serve dist/ from a separate asset domain and want SRI, compute the digests in your own pipeline; the two files are stable names, so a openssl dgst -sha384 -binary | openssl base64 -A over css/adminvora.min.css and js/adminvora.js is the whole job.
Warning — SRI cannot be used on the lazily imported vendor modules:
import()has no integrity option. If your threat model requires integrity on every file, serve from the same origin.
Licence aggregation
npm run vendor regenerates NOTICE.md: a summary table, then the complete text of every licence, read from each package's own LICENSE file rather than retyped.
markdown
# Third-party notices
| Package | Version | Licence |
|---|---|---|
| [`apexcharts`](https://apexcharts.com) | 3.54.1 | MIT |
---
## apexcharts 3.54.1
Licence: **MIT** · <https://apexcharts.com>
The MIT License (MIT)
Copyright (c) 2018 ApexCharts
Permission is hereby granted, free of charge, to any person obtaining a copy
…the entire licence, not an excerpt…Ship NOTICE.md with your application. build-dist.mjs puts it in dist/ and every starter kit copies it into the public asset root, so for most consumers this happens by itself.
The text, not the name. For a year this file was the summary table alone. That is a bibliography, not attribution: MIT and BSD-2 require the notice to be included "in all copies", and Apache-2.0 requires the licence plus any
NOTICEthe package ships (§4(d)). The file existed, the build's existence check passed, and the bundle was non-compliant the whole time — in a product people pay for, propagated into their asset roots by every kit.Two gates now sit on it.
vendor-sync.mjsfails if a package has no discoverable licence file, under any of the ten filenames packages actually use, because a dependency whose terms cannot be reproduced cannot be redistributed.build-dist.mjsfails ifNOTICE.mddoes not carry a section of licence text per vendored package, so "present" can no longer be mistaken for "sufficient".
Attribution is a licence requirement for MIT, BSD, and Apache-2.0 code. See License & Attribution.
Adding a new vendor: checklist
- [ ] Licence is MIT / BSD / Apache-2.0 / ISC / OFL — no GPL, no "free for personal use"
- [ ] Ships an ESM build (or a documented UMD interop wrapper is added, or its bare specifiers are rewritten with
provides/rewriteImports— in that order of preference) - [ ] Adds < 60 KB gzipped, or the value clearly justifies more
- [ ] Actively maintained (a release within 12 months) with no open critical CVEs
- [ ] Exposes a
destroy()/dispose()method - [ ] Keyboard-accessible, or we wrap it to make it so
- [ ] Can be themed from CSS custom properties
- [ ] Entry added to
vendor.manifest.jsonwith a pinned version and checksum - [ ] CSS import added to
vendor/_third-party.scssinside@layer bootstrap - [ ] Restyling partial created in
plugins/— check the vendor is not injecting its CSS unlayered first. style-mod does, and an unlayered declaration beats every@layer, so a partial written against such a vendor compiles, ships and does nothing. CodeMirror is themed throughEditorView.theme()for this reason - [ ] Loader entry added in
core/loader.js - [ ] Documented in Integration Index
- [ ]
npm run sizestill passes
Read next: Design Principles.