Skip to content

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 ​

ReasonConsequence of a CDN
CSPEnterprise policies commonly forbid third-party origins entirely. script-src 'self' breaks any CDN script.
GDPRGerman and Dutch courts have ruled that loading Google Fonts transmits IPs without consent. Fines have been issued.
Air-gapped deploymentsGovernment, healthcare, and finance networks have no outbound internet.
AvailabilityA CDN outage takes your admin panel down with it.
Supply-chain attacksPolyfill.io (2024) served malware to 100k+ sites through a domain sale. cdnjs/unpkg have no equivalent guarantee.
Unpublishingleft-pad (2016) proved a package can vanish from under you.
PerformanceCross-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 developmentWorking 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 mismatch

Result: 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" }
      ]
    }
  }
}
FieldPurpose
versionMust match package.json exactly; the tool verifies
licenseAggregated into NOTICE.md at build time
from / toSource path inside the package → destination in src/vendor/
sha256Integrity check; a mismatch aborts the build
layerIf present, the CSS is wrapped in @layer <name> on import
providesThe bare specifier this file answers to, for a package other vendored files import
rewriteImportsRewrite this file's bare specifiers to relative paths on the way in
subsetFor 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 upgrade

Upgrading 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 NOTICE the 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.mjs fails 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.mjs fails if NOTICE.md does 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.json with a pinned version and checksum
  • [ ] CSS import added to vendor/_third-party.scss inside @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 through EditorView.theme() for this reason
  • [ ] Loader entry added in core/loader.js
  • [ ] Documented in Integration Index
  • [ ] npm run size still passes

Read next: Design Principles.

Documentation for @creativeigniter/adminvora