03-app-structure/02-index-html.md

index.html

index.html is the root HTML bootstrap file for a Vroq app.

It should stay small and predictable. Its job is to start the app, not to contain app logic.

Responsibilities

index.html should:

load /vroqjs/{{app.vroqjs}}/ui.css
define the import map
set window.__VROQ_RELEASE__ from app.json
create the root mount node
load App.js as a module

Standard pattern

Use this pattern unless there is a strong reason not to:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>App</title>
    <link rel="stylesheet" href="/vroqjs/{{app.vroqjs}}/ui.css" />
    <script>
      window.__VROQ_RELEASE__ = {{app.release}};
    </script>
    <script type="importmap">
{
  "imports": {
    "/vroqjs/": "/ignore--{{app.time}}/vroqjs/{{app.vroqjs}}/",
    "@app/": "./ignore--{{app.time}}/",
    "codemirror": "https://esm.sh/codemirror?target=es2022",
    "@codemirror/state": "https://esm.sh/@codemirror/state?target=es2022",
    "@codemirror/view": "https://esm.sh/@codemirror/view?target=es2022",
    "@codemirror/commands": "https://esm.sh/@codemirror/commands?target=es2022",
    "@codemirror/lang-javascript": "https://esm.sh/@codemirror/lang-javascript@6?target=es2022"
  }
}
</script>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/ignore--{{app.time}}/App.js"></script>
  </body>
</html>

app.json requirement

Every app should include an app.json file.

Standard pattern:

{
  "version": 1,
  "vroqjs": "v02",
  "release": false
}

The vroqjs value selects the framework version used by the app.

The release value is the source of truth for whether the app is running in release mode.

false means development mode
true means release mode

index.html should set:

window.__VROQ_RELEASE__ = {{app.release}};

This global flag should be treated as the source of truth for the whole app when deciding whether development-only tooling such as RPC debugging should be enabled.

If a prompt does not specify a framework version, use:

v02

Rules

do not put feature logic in index.html
do not omit ui.css
do not invent a different root node id without a clear reason
do not place large inline scripts in this file
use {{app.vroqjs}} in index.html instead of hard-coding a framework version
set window.__VROQ_RELEASE__ from {{app.release}}
include app.json with version, vroqjs, and release

Why consistency matters

A standard index.html lets ChatGPT quickly understand how the app loads and where the root runtime starts.

The {{app.vroqjs}} value also makes it clear which framework version the app should use.

The {{app.release}} value makes it clear whether the whole app is running in release mode, and window.__VROQ_RELEASE__ should be treated as the runtime source of truth for that setting.

Final rule

Keep index.html as a small, boring, standard bootstrap file.