Skip to content

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.

AssetRawGzipped
adminvora.min.css407.1 KiB53.0 KiB
tokens.css119.6 KiB18.4 KiB
adminvora.js431.3 KiB126.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.

RawGzipped
adminvora.js — what a customer installs431.3 KiB126.7 KiB
demo/demo.js — the demo screens only186.9 KiB50.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:

VendorGzippedLoaded by
CodeMirror291 KiBthe code editor
ApexCharts140 KiBany data-av-chart
Tabulator104 KiBdata-av-datagrid with grouping
Quill59 KiBthe rich-text editor
FilePond45 KiBthe uploader
Leaflet45 KiBthe map
Sortable.js27 KiBdrag-and-drop lists
GLightbox18 KiBthe lightbox
Tom Select17 KiBenhanced selects
IMask16 KiBmasked 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 demand

Everything 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 ​

TechniqueImpact
Cascade layersNo specificity escalation, no !important bloat
Flat specificity (max 0-3-0)Faster selector matching
contain: layout style on cardsBounds layout invalidation
content-visibility: auto on long listsSkips off-screen rendering entirely
No * selectors outside the resetAvoids full-document recalculation
:has() avoided in tables and long listsInvalidation is expensive at scale
One stylesheet, no framework baselineThere is no Bootstrap layer to trim — the .av-* layer is all of it
Selective component compilationDelete 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 ​

TechniqueWhere
CSS animations over JSAll simple transitions
Web Animations API (Motion One)Composited off-thread
requestAnimationFrame throttlingPointer-driven effects
IntersectionObserver over scroll listenersScrollspy, reveal, lazy init
ResizeObserver over resize listenersChart and grid resizing
{ passive: true } on scroll/touchPrevents scroll blocking
Debounce on search input300 ms
Abort in-flight fetchesOn 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 ​

RowsStrategy
< 200Render everything
200–1,000content-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 ​

RuleReason
width + height on every <img>Reserves space → no CLS
loading="lazy" below the fold onlyNever on the LCP image
decoding="async"Does not block the main thread
srcset + sizesCorrect resolution per viewport
WebP with a JPEG fallback25–35% smaller
SVG for icons and illustrationsResolution-independent, themeable, tiny
Fonts split by script, each behind a unicode-rangeA page downloads only the scripts it renders
font-display: swapText 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 docs

docs: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.

  1. 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.
  2. Serve the minified stylesheet. adminvora.min.css, not adminvora.css — 43.9 KiB gzipped against 626 KiB raw unminified.
  3. Delete @use lines. src/scss/adminvora.scss is a flat list with no conditionals; removing a component you do not use and running npm run build:css genuinely removes its rules. Crude next to a configuration map, but real — see How the stylesheet is configured.
  4. 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.
  5. 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.
  6. 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-patternCost
Loading all vendor libraries eagerly+400 KB on every page
Rendering 5,000 table rows3–8 s of layout, unusable scroll
Unthrottled scroll listenersDropped frames, janky scroll
Animating width/height/topLayout on every frame
Permanent will-changeWasted GPU memory
Unbounded live-updating chartsPinned CPU core
Polling in a background tabHundreds of pointless requests
Base64 images in CSSBlocks the render-critical stylesheet
@import in CSSSerialised requests
Missing width/height on imagesCLS penalty
loading="lazy" on the LCP imageDelays LCP by hundreds of ms

Read next: Browser Support.

Documentation for @creativeigniter/adminvora