A modern HTTP web server index for Apache httpd, lighttpd, nginx, and other PHP-capable servers.

Replaces the default directory listing with a feature-rich interface: icons, thumbnails, previews, search, sorting, filtering, and more.

This is a fork of lrsjng's h5ai, which is no longer maintained.

• PHP 7.0.0+ (tested with PHP 8.4.0)
• A web server: Apache httpd, nginx, lighttpd, or Cherokee
• PHP GD extension (for image thumbnails)

git clone https://github.com/flowerey/h5ai.git
cd h5ai
npm install
npm run build

The build produces a ready-to-deploy _h5ai/ folder in build/.

1. Copy the entire _h5ai/ folder from build/ to your document root.
2. Make the cache directories writable by the web server:

   chown -R www-data:www-data _h5ai/public/cache _h5ai/private/cache

3. Configure your web server (see Server Configuration).
4. Access the info page at http://yourserver/_h5ai/ to verify the setup.

Important: Do not install files from src/ directly — they must be preprocessed via the build.

_h5ai/
  public/              ← Web-accessible
    index.php          ← Entry point
    cache/             ← Thumbnail cache (writable)
    css/styles.css     ← Compiled CSS
    ext/               ← Custom user scripts/styles
    images/            ← Icons, themes, fallback images
    js/scripts.js      ← Bundled JavaScript
  private/             ← NOT web-accessible
    cache/             ← Server-side cache
    conf/              ← Configuration (options.json, types.json, l10n/)
    php/               ← PHP application code

Place this in your site's <VirtualHost> or .htaccess at the document root:

DirectoryIndex index.html index.php

RewriteEngine On

# Route all directory requests through h5ai
RewriteRule ^/$ /_h5ai/public/index.php [L,QSA]
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI}/index\.(html|php)$
RewriteRule ^(.+)$ /_h5ai/public/index.php [L,QSA]

Ensure these modules are enabled: mod_rewrite, mod_headers, mod_expires, mod_deflate.

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    index index.html index.php;

    location / {
        try_files $uri $uri/ /_h5ai/public/index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

server.modules += ("mod_rewrite")

url.rewrite-if-not-file = (
    "^/(.*)/$" => "/_h5ai/public/index.php/$1"
)

All options live in _h5ai/private/conf/options.json. Key sections:

See options.json for the full list with documentation.

File type mappings are in types.json.

• Node.js ≥ 22.22.0 (or ≥ 24.15.0, or ≥ 26.0.0)
• npm ≥ 10.0.0

npm install          # Install dependencies
npm run lint         # Lint with ESLint
npm test             # Run tests with Vitest
npm run build        # Development build (with sourcemaps)
npm run build -- --release  # Production build (minified, creates zip)

The build script (scripts/build.mjs) processes:

1. JavaScript — esbuild bundles src/_h5ai/public/js/scripts.js as an IIFE, with pre.js (browser feature detection) prepended as a banner.
2. CSS — src/_h5ai/public/css/styles.less is compiled via Less, then post-processed with Autoprefixer and cssnano.
3. Templates — Pug templates in src/_h5ai/private/php/pages/ are compiled to PHP.
4. Static assets — PHP classes, images, config files, and root markdown files are copied with {{VERSION}} replaced.
5. Release zip — build/h5ai-<version>.zip is created with all deployment files.

src/_h5ai/
  private/
    conf/               ← Configuration files (options.json, types.json, l10n/)
    php/
      class-bootstrap.php  ← Entry point, autoloading, routing
      core/                ← Core classes (API, context, session, setup, ...)
      ext/                 ← Extensions (archive, search, thumb, custom, cachedb)
      pages/               ← Pug templates → PHP pages
  public/
    index.php           ← Web entry point
    css/                ← LESS source → compiled to styles.css
    js/
      lib/              ← Source JS modules
        core/           ← Core (location, types, event, ...)
        ext/            ← 18 extension modules
        main/           ← Entry points (index.js, info.js)
        model/          ← Data models (item.js)
        util/           ← DOM, utilities
        view/           ← View components (sidebar, notifications, ...)
      pre.js            ← Browser feature detection
    images/
      themes/           ← Icon themes (comity/, default/)
      ui/               ← UI SVG icons
    ext/                ← User custom scripts/styles

Tests run under Vitest with a jsdom environment:

npm test

Test files live in test/tests/ and use ES module imports.

MIT License — Copyright (c) 2020 Lars Jung (https://larsjung.de)

See the full license text.

h5ai uses these projects (all MIT-licensed):

• highlight.js — Syntax highlighting
• marked — Markdown rendering
• qrcode — QR code generation
• normalize.css — CSS reset
• Material Design Icons — Some icons (CC BY 4.0)

• Original project: https://github.com/lrsjng/h5ai
• This fork: https://github.com/flowerey/h5ai
• Issues: https://github.com/flowerey/h5ai/issues
• Releases: https://github.com/flowerey/h5ai/releases
• Icon themes: https://github.com/lrsjng/h5ai-themes