Project-Defined HTML Preloader Customization

Published Updated
Guidelines for authoring self-contained HTML preloaders (src/preloader.html), inlining CSS/JS and Base64 assets, container element scoping, and CLI publishing workflow.

A custom preloader is a self-contained HTML page (preloader.html) managed in the project codebase. During publishing, the Aircada CLI validates and uploads this file. The rendering engine then fetches and overlays this HTML instantly, replacing the default loading indicator before heavy 3D engine bundles, assets, and shaders load.

1. File Location & Configuration

By default, the CLI looks for the preloader at: src/preloader.html (relative to project root).

You can customize this path in air.config.json by adding a 'preloader' property:

json
{
  "appId": "your-app-id",
  "version": "1.0.0",
  "preloader": "https://aircadapublicassets.blob.core.windows.net/air-library/nodes/docs/sdk/guides/preloader/assets/custom-loader.html"
}

2. Code Guidelines (Strict Self-Containment)

Because only the single HTML file is uploaded to the cloud, the preloader must be fully self-contained:

  • Inlined CSS & JS: All custom styles must be contained within <style> blocks, and all logic within <script> blocks. External links (e.g. <link rel="stylesheet" href="style.css">) are not resolved.
  • Inlined Assets (SVGs & Base64): Relative image references like <img src="./logo.png"> will fail in production. Use inline <svg> tags or Base64 Data URIs: <img src="data:image/png;base64,...">.
  • DOM Overlay Scoping: Wrap your preloader design inside a main container element with the standard ID #aircada-preloader-container or #aircada-preloader with full-viewport absolute positioning.

3. Publishing Workflow (air publish)

When executing air publish, the Aircada CLI executes processPreloader() to validate the file. If un-inlined relative paths are detected, the CLI outputs a diagnostic warning to alert developers before upload.

  • Self-Contained HTML: All CSS, JS, and assets must be completely inlined in src/preloader.html.
  • Base64 & Inline SVG: Never use relative image URLs; embed SVGs or Base64 data URIs.
  • Container ID: Use #aircada-preloader-container with full viewport absolute positioning.
  • CLI Validation: air publish automatically validates and uploads custom preloaders.
src/preloader.html (html)
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <style>
    #aircada-preloader-container {
      position: absolute;
      inset: 0;
      z-index: 999999;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      background: #09090b;
      color: #fafafa;
      font-family: system-ui, -apple-system, sans-serif;
    }
    .spinner {
      width: 40px;
      height: 40px;
      border: 3px solid rgba(255, 255, 255, 0.1);
      border-top-color: #10b981;
      border-radius: 50%;
      animation: spin 1s linear infinite;
    }
    @keyframes spin {
      to { transform: rotate(360deg); }
    }
  </style>
</head>
<body>
  <div id="aircada-preloader-container">
    <div class="spinner"></div>
    <p style="margin-top: 16px; font-size: 14px; opacity: 0.8;">Loading 3D Experience...</p>
  </div>
</body>
</html>
Self-contained HTML preloader template with inline CSS and container scoping