Appearance
Static HTML
Zero build step. Copy dist/, write HTML, done.
When this is the right choice
- Prototyping or client demos
- A backend that renders HTML (PHP, Python, Ruby, Java, .NET) with no frontend build
- Internal tools where a Node toolchain is not justified
- Documentation or marketing pages alongside the app
You give up: SCSS customisation, tree-shaking, and Handlebars partials. You keep: every component, every theme, every module.
Setup
public/
├── adminvora/
│ ├── css/adminvora.min.css
│ ├── js/adminvora.js
│ ├── vendor/ ← lazy third-party modules, keep beside js/
│ ├── img/
│ ├── LICENSE.md
│ └── NOTICE.md
├── index.html
├── orders.html
└── settings.htmlhtml
<!doctype html>
<html lang="en" data-bs-theme="light" data-av-preset="aurora" data-av-layout="vertical">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<meta name="color-scheme" content="light dark">
<title>Dashboard · Acme</title>
<script>
(function(){var d=document.documentElement,s;try{s=JSON.parse(localStorage.getItem('adminvora.prefs')||'{}')}catch(e){s={}}
var m=s.mode||'system',k=m==='dark'||(m==='system'&&matchMedia('(prefers-color-scheme: dark)').matches);
d.setAttribute('data-bs-theme',k?'dark':'light');
['preset','style','layout','nav-skin','density','radius','sidebar','topbar','width','contrast','motion','depth'].forEach(function(x){s[x]&&d.setAttribute('data-av-'+x,s[x])});
s.dir&&d.setAttribute('dir',s.dir);d.classList.add('av-booting');
requestAnimationFrame(function(){requestAnimationFrame(function(){d.classList.remove('av-booting')})})})();
</script>
<!-- Optional: fetch the above-the-fold face early. The bundle ships it in vendor/fonts/. -->
<link rel="preload" href="/adminvora/vendor/fonts/inter/inter-latin-opsz-normal.woff2" as="font" type="font/woff2" crossorigin>
<link rel="stylesheet" href="/adminvora/css/adminvora.min.css">
</head>
<body>
<a href="#main" class="av-skip-link">Skip to main content</a>
<div class="av-shell">
<aside class="av-sidebar" id="avSidebar">…</aside>
<div class="av-main">
<header class="av-topbar">…</header>
<main class="av-content" id="main" tabindex="-1">
<div class="container-fluid">…</div>
</main>
<footer class="av-footer">…</footer>
</div>
</div>
<script src="/adminvora/js/adminvora.js" defer></script>
</body>
</html>The duplication problem
Fifty pages, each with the same sidebar. Someone adds a menu item and has to edit fifty files. Three solutions, in order of preference.
1. Server-side includes (best if you have a backend)
php
<?php include 'partials/head.php'; ?>
<body>
<?php include 'partials/sidebar.php'; ?>
…html
<!--#include virtual="/partials/sidebar.html" -->jinja
{% include "partials/sidebar.html" %}2. Web components (no build, no backend)
js
// components/av-sidebar.js
class AvSidebar extends HTMLElement {
async connectedCallback() {
const res = await fetch('/partials/sidebar.html');
this.innerHTML = await res.text();
// Mark the current page
const path = location.pathname;
this.querySelector(`a[href="${path}"]`)?.closest('.av-menu__item')
?.classList.add('av-menu__item--active');
this.querySelector(`a[href="${path}"]`)?.setAttribute('aria-current', 'page');
AdminVora.init(this);
}
}
customElements.define('av-sidebar', AvSidebar);html
<av-sidebar></av-sidebar>Warning — this fetches the partial at runtime, which delays first paint and breaks with JavaScript disabled. Acceptable for internal tools; not for anything public-facing.
3. Build the HTML once
Even without adopting a frontend framework, a 20-line script beats maintaining fifty copies.
bash
npm i -D handlebars glob
node build.mjsjs
// build.mjs
import Handlebars from 'handlebars';
import { globSync } from 'glob';
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { dirname, join, relative } from 'node:path';
for (const f of globSync('src/partials/**/*.hbs')) {
Handlebars.registerPartial(
relative('src/partials', f).replace(/\.hbs$/, '').replace(/\\/g, '/'),
readFileSync(f, 'utf8'));
}
const layout = Handlebars.compile(readFileSync('src/layout.hbs', 'utf8'));
for (const f of globSync('src/pages/**/*.hbs')) {
const rel = relative('src/pages', f).replace(/\.hbs$/, '.html');
const html = layout({
body: new Handlebars.SafeString(Handlebars.compile(readFileSync(f, 'utf8'))({})),
current: '/' + rel.replace(/\\/g, '/')
});
const out = join('public', rel);
mkdirSync(dirname(out), { recursive: true });
writeFileSync(out, html);
}This is what AdminVora's own html/ directory does. Full implementation: Build Pipeline.
Active navigation without a build
js
// active-nav.js — include once, works on every page
(function () {
const path = location.pathname.replace(/\/index\.html$/, '/');
document.querySelectorAll('.av-menu__link[href]').forEach((link) => {
const href = link.getAttribute('href');
if (href === path || (href !== '/' && path.startsWith(href))) {
link.setAttribute('aria-current', 'page');
link.closest('.av-menu__item')?.classList.add('av-menu__item--active');
// Open all ancestor groups
let group = link.closest('.av-menu__sub')?.closest('.av-menu__item');
while (group) {
group.classList.add('av-menu__item--open');
group.querySelector('.av-menu__link')?.setAttribute('aria-expanded', 'true');
group = group.parentElement.closest('.av-menu__item');
}
}
});
})();Deployment
Any static host works: Netlify, Vercel, Cloudflare Pages, GitHub Pages, S3 + CloudFront, or nginx.
nginx
nginx
server {
listen 443 ssl http2;
root /var/www/app;
index index.html;
# Hashed assets — cache forever
location ~* \.(woff2|svg|png|webp|jpg)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# CSS/JS — revalidate (they are not content-hashed in the dist build)
location ~* \.(css|js)$ {
expires 1h;
add_header Cache-Control "public, must-revalidate";
}
# HTML — never cache
location ~* \.html$ {
expires -1;
add_header Cache-Control "no-cache";
}
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
error_page 404 /404.html;
error_page 500 502 503 504 /500.html;
gzip on;
gzip_types text/css application/javascript image/svg+xml application/json;
gzip_min_length 1024;
}Netlify
toml
# netlify.toml
[build]
publish = "public"
[[headers]]
for = "/fonts/*"
[headers.values]
Cache-Control = "public, max-age=31536000, immutable"
Access-Control-Allow-Origin = "*"
[[headers]]
for = "/*.html"
[headers.values]
Cache-Control = "no-cache"
X-Content-Type-Options = "nosniff"
Content-Security-Policy = "default-src 'self'; script-src 'self' 'sha256-…'; style-src 'self'; font-src 'self'; img-src 'self' data:"
[[redirects]]
from = "/*"
to = "/404.html"
status = 404The boot script needs either a nonce or a hash in the CSP. For a static host, use a hash:
bash
echo -n '(function(){…})();' | openssl dgst -sha256 -binary | openssl base64Common mistakes
| Mistake | Symptom | Fix |
|---|---|---|
| Boot script placed after the stylesheet | White flash in dark mode | Move it above <link> |
| Boot script in an external file | White flash | It must be inline and synchronous |
vendor/ renamed or moved | Charts, grids and editors never load; nothing else changes | Keep it beside js/, or set window.__AV_ASSET_BASE__ to the directory the runtime is served from |
Missing crossorigin on font preload | Font downloads twice | Add crossorigin |
| Absolute paths on a sub-path deploy | 404s everywhere | Use relative paths or a <base> tag |
file:// protocol | Modules and fetch fail (CORS) | Serve over HTTP — npx serve public |
| Opening HTML directly from the file manager | Same as above | Same |
Local development
bash
npx serve public
npx http-server public -p 8080
python -m http.server 8080 --directory public
php -S localhost:8080 -t publicAny of these works. What does not work is double-clicking the HTML file — ES modules and fetch are blocked on file://.
Upgrading
bash
# Replace the whole directory; do not merge
rm -rf public/adminvora
unzip adminvora-1.1.0-dist.zip -d public/Your HTML is untouched. Check CHANGELOG.md in the package for any breaking markup changes before upgrading a major version.
Checklist
- [ ] Boot script is inline, synchronous, and first in
<head> - [ ] Fonts preloaded with
crossorigin - [ ]
vendor/besidejs/, both copied fromdist/ - [ ] Served over HTTP, not
file:// - [ ] Shared markup extracted (includes, web components, or a build script)
- [ ] Active navigation state applied
- [ ] Custom 404 and 500 pages configured in the web server
- [ ] Security headers set
- [ ] Correct cache headers per asset type
- [ ] CSP allows the boot script by hash or nonce
Read next: Laravel.