Appearance
Performance
Budgets are enforced in CI. A pull request that exceeds one fails.
What it actually transfers
Measured with npm run inventory, which gzips the shipped files and is held to these figures by npm run check:inventory — so a change that moves them fails the build here rather than going stale in prose. The numbers below are for the complete product: every preset, every layout, every component.
| Asset | Raw | Gzipped |
|---|---|---|
adminvora.min.css | 407.1 KiB | 53.0 KiB |
tokens.css | 119.6 KiB | 18.4 KiB |
adminvora.js | 431.3 KiB | 126.7 KiB |
Two of those numbers deserve comment.
The runtime is large, and it is one file. 108 KiB gzipped is what a single unbundled, unminified IIFE costs. There is no minifier in this build, so this is the honest number and it is still above where it will land.
It used to be 159 KiB. The difference is the runtime split: the 36 demo-page controllers that drive the demo screens — the mail client's state, the kanban board, the checkout, the categories drawer — were a third of the file and are not the product. They now live in src/demo/demo.js, which ships with the demo pages and is not in dist/, so nothing a customer installs carries them. The eight starter kits copy dist/ and were the largest beneficiaries: they never ran a line of it.
| Raw | Gzipped | |
|---|---|---|
adminvora.js — what a customer installs | 431.3 KiB | 126.7 KiB |
demo/demo.js — the demo screens only | 186.9 KiB | 50.9 KiB |
The second row is not a budget a customer pays. It is here so the first row can be read as what it is rather than as a number that quietly excludes something.
Vendors are not in it. They lazy-load from vendor/ on first use, keyed by feature rather than by page, so a page with no chart never fetches ApexCharts. That is the largest performance lever in the product and it needs no configuration:
| Vendor | Gzipped | Loaded by |
|---|---|---|
| CodeMirror | 291 KiB | the code editor |
| ApexCharts | 140 KiB | any data-av-chart |
| Tabulator | 104 KiB | data-av-datagrid with grouping |
| Quill | 59 KiB | the rich-text editor |
| FilePond | 45 KiB | the uploader |
| Leaflet | 45 KiB | the map |
| Sortable.js | 27 KiB | drag-and-drop lists |
| GLightbox | 18 KiB | the lightbox |
| Tom Select | 17 KiB | enhanced selects |
| IMask | 16 KiB | masked inputs |
There is no size gate, no Lighthouse CI and no Core Web Vitals measurement in this repository. npm run test:pages fails on any request leaving the origin, so the no-third-party property is enforced.
Loading strategy
The critical path
1. HTML arrives
2. Inline boot script runs ~0.4 ms, parser-blocking (intentional)
3. CSS downloads and applies render-blocking, 108 KB gz
4. Preloaded font arrives 28 KB, no CLS (metric overrides)
5. First Contentful Paint ◄── nothing above requires JavaScript
6. adminvora.js executes (defer) 52 KB gz, after parse
7. Modules initialise
8. Lazy chunks fetched on demandEverything visible at FCP is CSS-only. A user on a broken connection still sees a fully-styled, readable page.
Resource hints
html
<!-- Preload only the above-the-fold font -->
<link rel="preload" href="/adminvora/vendor/fonts/inter/inter-latin-opsz-normal.woff2" as="font" type="font/woff2" crossorigin>
<!-- Preload the CSS explicitly on slow connections -->
<link rel="preload" href="/css/adminvora.min.css" as="style">
<link rel="stylesheet" href="/css/adminvora.min.css">
<!-- Warm the chart vendor on a dashboard route. There are no hashed chunks in
this build: the lazy modules are served from vendor/, under their own
names, beside js/. -->
<link rel="modulepreload" href="/adminvora/vendor/apexcharts/apexcharts.esm.js">Do not preload all three fonts. Each preload competes with the LCP resource for bandwidth.
Lazy vendors
Each vendor is a separate file under vendor/, keyed by feature, not by route: ten pages using charts share one download, and a page without a chart requests none. Charts additionally wait until their element is within 200px of the viewport, so a dashboard renders the charts on screen first and the rest as you scroll. There is no way to preload a vendor deliberately.
CSS performance
| Technique | Impact |
|---|---|
| Cascade layers | No specificity escalation, no !important bloat |
| Flat specificity (max 0-3-0) | Faster selector matching |
contain: layout style on cards | Bounds layout invalidation |
content-visibility: auto on long lists | Skips off-screen rendering entirely |
No * selectors outside the reset | Avoids full-document recalculation |
:has() avoided in tables and long lists | Invalidation is expensive at scale |
| One stylesheet, no framework baseline | There is no Bootstrap layer to trim — the .av-* layer is all of it |
| Selective component compilation | Delete a component's @use line in src/scss/adminvora.scss and rebuild |
scss
.av-card { contain: layout style; }
.av-list--long > .av-list__item {
content-visibility: auto;
contain-intrinsic-size: auto 64px; /* prevents scrollbar jump */
}contain-intrinsic-size is essential with content-visibility. Without it, the scrollbar resizes as items render, which is worse than not using it at all.
JavaScript performance
Avoid main-thread blocking
| Technique | Where |
|---|---|
| CSS animations over JS | All simple transitions |
| Web Animations API (Motion One) | Composited off-thread |
requestAnimationFrame throttling | Pointer-driven effects |
IntersectionObserver over scroll listeners | Scrollspy, reveal, lazy init |
ResizeObserver over resize listeners | Chart and grid resizing |
{ passive: true } on scroll/touch | Prevents scroll blocking |
| Debounce on search input | 300 ms |
| Abort in-flight fetches | On every new keystroke |
js
// The rAF throttle pattern — pointermove fires far above the refresh rate
let frame = 0;
el.addEventListener('pointermove', (e) => {
cancelAnimationFrame(frame);
frame = requestAnimationFrame(() => update(e));
}, { passive: true, signal });Long lists
| Rows | Strategy |
|---|---|
| < 200 | Render everything |
| 200–1,000 | content-visibility: auto |
| 1,000+ | Virtual scrolling, or server-side pagination |
Memory
Every module uses AbortSignal cleanup, WeakMap instance storage, and explicit vendor destroy(). Verified by an automated heap test:
js
// tests/e2e/memory.spec.js
test('no leak after mount/destroy cycles', async ({ page }) => {
await page.goto('/orders');
const client = await page.context().newCDPSession(page);
await client.send('HeapProfiler.collectGarbage');
const before = (await client.send('Runtime.getHeapUsage')).usedSize;
for (let i = 0; i < 50; i++) {
await page.evaluate(() => {
const el = document.querySelector('#grid');
AdminVora.destroy(el);
AdminVora.init(el);
});
}
await client.send('HeapProfiler.collectGarbage');
const after = (await client.send('Runtime.getHeapUsage')).usedSize;
expect(after).toBeLessThan(before * 1.05);
});Images and fonts
| Rule | Reason |
|---|---|
width + height on every <img> | Reserves space → no CLS |
loading="lazy" below the fold only | Never on the LCP image |
decoding="async" | Does not block the main thread |
srcset + sizes | Correct resolution per viewport |
| WebP with a JPEG fallback | 25–35% smaller |
| SVG for icons and illustrations | Resolution-independent, themeable, tiny |
Fonts split by script, each behind a unicode-range | A page downloads only the scripts it renders |
font-display: swap | Text visible immediately |
The bundled faces are declared in src/scss/base/_fonts.scss. No metric overrides are set, so the swap from the fallback can reflow a line on a cold load; preloading the Latin Inter face (below) narrows that window.
Caching
nginx
# Content-hashed assets — cache forever
location ~* -[a-f0-9]{8}\.(js|css)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# Fonts and icons — rarely change
location ~* \.(woff2|svg)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# Unhashed CSS/JS — revalidate
location ~* \.(js|css)$ {
expires 1h;
add_header Cache-Control "public, must-revalidate";
}
# HTML — never cache
location ~* \.html$ {
add_header Cache-Control "no-cache";
}
gzip on;
gzip_types text/css application/javascript image/svg+xml application/json;
gzip_min_length 1024;
brotli on;
brotli_types text/css application/javascript image/svg+xml application/json;
brotli_comp_level 6;Brotli typically saves a further 15–20% over gzip on CSS and JS.
Measuring
Locally
There is no bundle analyser. What ships is a static host and one audit tool:
bash
npm run dev # serve the working tree at :5173
npx lighthouse http://localhost:5173/html/pages/dashboards/analytics.html --view
npx unlighthouse --site http://localhost:5173 # every page at once
npm run docs:audit # raw and gzip weight of the built docsdocs:audit measures the documentation site rather than the product, and it is the only weight budget with a command behind it today. The stylesheet and runtime are single files, so their sizes are read directly off src/css/adminvora.min.css and src/js/adminvora.js.
In production
js
// Report Core Web Vitals to your analytics
import { onCLS, onINP, onLCP, onTTFB } from 'web-vitals';
function send({ name, value, rating, id }) {
navigator.sendBeacon('/api/vitals', JSON.stringify({
metric: name, value: Math.round(value), rating, id,
path: location.pathname, connection: navigator.connection?.effectiveType
}));
}
onLCP(send); onINP(send); onCLS(send); onTTFB(send);Real-user data beats lab data. Lab numbers tell you if you regressed; RUM tells you what users actually experience on the devices they actually own.
AdminVora's own timings
There is no timing mode.
For per-module timing today, use the browser's own Performance panel: every vendor arrives as a separate network request under vendor/, which makes the lazy-load cost directly readable without any instrumentation from us.
Optimisation guide
The levers that exist today, in order of impact.
- Do nothing about the vendors. They already lazy-load from
vendor/on first use and are keyed by feature rather than by page, so a page with no chart never fetches ApexCharts. That is the largest single lever in the product and it is automatic. - Serve the minified stylesheet.
adminvora.min.css, notadminvora.css— 43.9 KiB gzipped against 626 KiB raw unminified. - Delete
@uselines.src/scss/adminvora.scssis a flat list with no conditionals; removing a component you do not use and runningnpm run build:cssgenuinely removes its rules. Crude next to a configuration map, but real — see How the stylesheet is configured. - Ship fewer font families. The bundle delivers none. The token stacks name three and fall back to the system stack, so what a page downloads here is entirely your choice and is zero by default.
- Call
AdminVora.destroy(root)before a route swap in a client-side router, so vendor instances and the three module-level observers are released rather than accumulating across navigations. - Server-render more. A chart that only ever appears in a print or email view can be a static SVG, and then its 140 KiB never loads at all.
There is no SCSS configuration map behind any of this — no @use 'adminvora' with (…) and no $av-… variables at all. See the build-pipeline page for what replaced that promise, and note that npm run check:scss-api is why this sentence cannot quietly become untrue again: naming one of those variables anywhere in this documentation, even to deny it, fails the build.
Swapping a vendor is not a configuration option: the loader's VENDORS map is a fixed set of keys in src/js/adminvora.js, so substituting a lighter charting library means editing that map and the module that drives it.
Anti-patterns
| Anti-pattern | Cost |
|---|---|
| Loading all vendor libraries eagerly | +400 KB on every page |
| Rendering 5,000 table rows | 3–8 s of layout, unusable scroll |
| Unthrottled scroll listeners | Dropped frames, janky scroll |
Animating width/height/top | Layout on every frame |
Permanent will-change | Wasted GPU memory |
| Unbounded live-updating charts | Pinned CPU core |
| Polling in a background tab | Hundreds of pointless requests |
| Base64 images in CSS | Blocks the render-critical stylesheet |
@import in CSS | Serialised requests |
Missing width/height on images | CLS penalty |
loading="lazy" on the LCP image | Delays LCP by hundreds of ms |
Read next: Browser Support.