Skip to content

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.html
html
<!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.mjs
js
// 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 = 404

The 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 base64

Common mistakes ​

MistakeSymptomFix
Boot script placed after the stylesheetWhite flash in dark modeMove it above <link>
Boot script in an external fileWhite flashIt must be inline and synchronous
vendor/ renamed or movedCharts, grids and editors never load; nothing else changesKeep it beside js/, or set window.__AV_ASSET_BASE__ to the directory the runtime is served from
Missing crossorigin on font preloadFont downloads twiceAdd crossorigin
Absolute paths on a sub-path deploy404s everywhereUse relative paths or a <base> tag
file:// protocolModules and fetch fail (CORS)Serve over HTTP — npx serve public
Opening HTML directly from the file managerSame as aboveSame

Local development ​

bash
npx serve public
npx http-server public -p 8080
python -m http.server 8080 --directory public
php -S localhost:8080 -t public

Any 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/ beside js/, both copied from dist/
  • [ ] 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.

Documentation for @creativeigniter/adminvora