Static sites
Use cases, project layout, and best practices for Chroma apps deployed to a plain static host, with the mistakes to avoid, drawn from a production portfolio site.
A lot of Chroma projects are not applications in the "dashboard" sense. They are landing pages, portfolios, product pages, and small tools that you upload once and serve from any file host. This guide covers that case: how to structure the project, what to automate, and which habits cost you performance, SEO, or maintainability.
Every recommendation below comes from a real site (a single-page portfolio with GSAP animations, a WebGL canvas, and full SEO metadata) built with Chroma and deployed as static files. The project needs no Node.js, no npm, and no node_modules: everything below runs with chroma dev, chroma preview, and chroma build, and the SEO and asset work is done by the CLI's build plugins. Measurements are from its dist/ output, and every framework behavior listed was checked against the engine source.
What "static" means here
Three different things are called "static" in Chroma. This page is about the second one.
| Term | Meaning | Where it is defined |
|---|---|---|
"mode": "static" in chroma.json | A build path: flat HTML and JS files, the WASM engine inlined into one chroma.js, no bundle. | chroma.json reference |
| Static hosting (this guide) | Any build, usually "mode": "dynamic", whose dist/ you upload to an HTTP host with no server code. This is the Portable (Web) runtime. | Runtime modes |
| A static HTML shell | HTML written into index.html at build time so crawlers and users without JavaScript see real content before the app mounts. | Pattern 2 |
The reference site uses "mode": "dynamic" (one bundled module plus a separate chroma_bg.wasm) and is still a static site, because the output is plain files. Choose mode by how you want to bundle, not by how you host.
When it fits
| Use case | Why it works | Watch out for |
|---|---|---|
| Portfolio, personal site | One page, content in a data module, a few interactive parts (menu, motion). | You must add the SEO shell yourself (Pattern 2). |
| Marketing or product landing page | Fast to deploy anywhere, no server, easy to preview. | No SSR: crawlers that do not run JavaScript see only what is in index.html. |
| Interactive widget on a content site | Mount render(App, el) into one element and keep the rest as plain HTML. | render() appends to the container; it never clears it. |
| Offline-capable tool, calculator, internal utility | A bucket or intranet file share is enough; state can use Chroma-Fs in the browser. | Storage is keyed to the deployment origin; a new host starts empty. |
It is a poor fit when pages must be generated per URL from a large content set, when you need server redirects or per-request logic, or when search ranking depends on server-rendered HTML for many routes. Chroma has no server-side rendering (Limitations); the shell pattern covers one page well and does not scale to hundreds.
Reference project
The site is one HTML entry, twelve components plus a ui.chr helper module, and a data module. There is no package.json and no scripts/ folder.
site/
├── chroma.json # mode: dynamic, build.jsEntry: src/main.chr, plugins: [chroma-seo, ...]
├── index.html # critical CSS, SEO tags, CDN scripts
├── src/
│ ├── main.chr # boot: mount, then start motion
│ ├── App.chr # root component tree
│ ├── components/ # Hero.chr, Projects.chr, Cta.chr, ui.chr, ...
│ ├── data/site.chr # single source of truth for all content
│ ├── lib/ # motion.chr, scroll.chr, icons.chr
│ └── styles/ # tokens.css, base.css, sections.css, motion.css
├── assets/ # optimized images and woff2 fonts
└── public/ # robots.txt, llms.txt, favicons, og-image (copied to the root of dist/)What the build ships:
| File | Size | Notes |
|---|---|---|
bundle.js | 57 KB (about 20 KB gzip) | Whole app plus the engine loader, minified |
chroma_bg.wasm | 111 KB | Must sit next to bundle.js |
index.html | 33 KB | Includes the generated shell and JSON-LD |
Best practices
1. Keep all content in one data module
Put every string, link, and list in one module that both the components and the build plugins read. Components render it, and the chroma-seo plugin uses the same data to write the <title>, meta tags, and JSON-LD. Nothing is copied by hand, so the page and its metadata cannot drift.
// src/data/site.chr
export const SITE_URL = "https://example.com/";
export const seo = { title: "Ana Ruiz, Designer", description: "Portfolio and product design." };
export const projects = { items: [{ title: "Case study", href: "/work/", image: { src: "/img/cover.jpg" } }] };// src/components/Projects.chr
import { projects } from "../data/site.chr";
// render projects.items with .map()It is a .chr module like the rest of src/, so the lint rules for .chr source apply without exceptions.
2. Ship a static HTML shell and replace it on mount
Because there is no SSR, put the real page content inside <div id="app"> in index.html. Crawlers, link previews, and visitors with scripts blocked read it directly. When the app boots it clears the shell and renders the same content.
Generate the shell instead of writing it. The chroma-seo build plugin injects it into index.html in chroma dev and chroma build; if you write it by hand, wrap the region in marker comments so it is easy to replace:
<div id="app">
<!-- seo:shell:start (generated from src/data/site.chr) -->
<main><!-- same structure as React output --></main>
<!-- seo:shell:end -->
</div>render() appends to its container. It does not clear it, so clear the shell first or you will show the page twice:
// src/main.chr
const mount = document.getElementById("app");
mount.replaceChildren(); // drop the static shell
render(App, mount);Rules that keep the shell trustworthy:
- Use the same class names and structure as the components, so styles apply to both.
- Keep exactly one
<h1>in the shell. - Generate JSON-LD from the data module instead of typing it, so a stray character cannot ship invalid structured data.
- Escape
</inside JSON-LD (<\/), otherwise it closes the<script>early. The plugin does this for you.
chroma build strips every HTML comment and the whitespace between tags from index.html (the content of <script>, <style>, <pre>, and <textarea> is left alone). Your marker comments disappear from dist/, which is fine, but a space between two inline elements (</a> <a>) is also removed. Put the space inside an element or use CSS gap.
3. Reference the entry file by its source path
The build replaces the text of build.jsEntry with build.outfile throughout index.html, using a plain substring replacement. Your source HTML must therefore contain the exact entry path.
<!-- source index.html -->
<script type="module" src="/src/main.chr"></script>
<!-- dist/index.html after chroma build -->
<script type="module" src="/bundle.js"></script>- Point the script at the entry (
main.chr), never at a component such asApp.chr. ImportAppfrom the entry. - Do not write the entry path anywhere else in the HTML (for example in visible text). Every occurrence is rewritten.
- If the script path does not contain the
jsEntrystring, the build leaves a.chrreference indist/and the page breaks.
4. Never let animation hide content
A static site must stay readable when scripts fail, load slowly, or the visitor prefers reduced motion. Hide elements only under a class that JavaScript adds, and remove it on any failure.
/* motion.css: hidden only when the boot script opts in */
.js-motion .hero__lead { opacity: 0; transform: translateY(24px); }
@media (prefers-reduced-motion: reduce) {
.js-motion .hero__lead { opacity: 1 !important; transform: none !important; }
}// src/main.chr
if (!reduceMotion) html.classList.add("js-motion");
const guard = setTimeout(() => html.classList.remove("js-motion"), 5000);
try {
await Promise.race([document.fonts.ready, sleep(1500)]);
initMotion(mount);
} catch (err) {
html.classList.remove("js-motion"); // content is never left hidden
} finally {
clearTimeout(guard);
}Also wait for fonts before measuring text (text splitting needs final metrics) with a time cap, so a slow font cannot block the page.
5. Load third-party scripts from a CDN safely
Animation and scroll libraries can come from a CDN as classic scripts. Pin the version, add Subresource Integrity, and use defer.
<link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin>
<script defer src="https://cdn.jsdelivr.net/npm/gsap@3.15.1/dist/gsap.min.js"
integrity="sha384-YOUR_SRI_HASH" crossorigin="anonymous"></script>
<script type="module" src="/src/main.chr"></script>Deferred classic scripts and module scripts both run after parsing, in document order, so the globals exist before main.chr runs. Read them from globalThis and guard for a failed download:
// src/lib/motion.chr
const { gsap, ScrollTrigger } = globalThis;
const HAS_GSAP = Boolean(gsap && ScrollTrigger);
export function initMotion(root) {
if (!HAS_GSAP) throw new Error("GSAP did not load from the CDN");
gsap.registerPlugin(ScrollTrigger);
}The caller catches that error (Pattern 4) and the page stays static and readable. With the VS Code extension, .chr files see these globals as any; declare them through the types map in chroma.json if you want checking (Linter).
6. Build a repeatable dist/
chroma build is the whole pipeline. It writes index.html and the bundle, copies chroma_bg.wasm, plugins/, and assets/, copies the contents of public/ to the root of dist/, and copies every local file that index.html points to (stylesheets, images, fonts). Build plugins add the generated files (sitemap, RSS, robots.txt, generated CSS) after the bundle. There is no postbuild step and nothing to chain with &&:
chroma validate
chroma build
chroma previewWhat to keep in mind:
- Put originals you do not want to publish (for example
.ttffonts or full-size PNG sources) outsideassets/andpublic/, because both folders are copied as they are. - Keep stylesheets as plain
.cssfiles thatindex.htmllinks: they are copied unchanged. Use Chroma-Style when you want generated, minified CSS. - A missing file that
index.htmlreferences is not copied and not reported; open the page inchroma previewand check the network tab (see the next pattern).
7. Optimize what the browser fetches first
- Fonts. Ship
.woff2only, withfont-display: swap, and preload the one or two faces used above the fold:<link rel="preload" href="/assets/fonts/…woff2" as="font" type="font/woff2" crossorigin>. Thecrossoriginattribute is required even for same-origin fonts. - Images. Generate
.webpat two widths and usesrcsetandsizes. Always setwidthandheightso the layout does not shift. Mark the hero imagefetchpriority="high"and everything below the foldloading="lazy". - Critical CSS. Inline a few lines (background and text color) in
<head>so there is no white flash beforemain.cssarrives. - Metadata. Include
canonical, Open Graph and Twitter tags, a web manifest,robots.txt,sitemap.xml, andllms.txtif you want AI crawlers to find a plain summary.
8. Preview exactly what you deploy
The dev server serves your source files, so it is not a production test. After chroma build, serve dist/:
chroma preview # serves dist/ on dev.port, no live reload
chroma dev --static # same thing
chroma preview --port 4175 # explicit portCheck three things in the network tab: bundle.js and chroma_bg.wasm return 200, chroma_bg.wasm has Content-Type: application/wasm, and the page never requests /src/main.chr or /pkg/chroma.js (those exist only in development). Never open dist/index.html from file://; browsers do not run WASM from there.
9. Configure the host for the output you actually have
| Setting | Do this | Why |
|---|---|---|
| Document root | dist/ at the domain root | The build writes absolute paths (/bundle.js, /assets/…, /plugins/…). A sub-path such as /repo/ breaks them. |
.wasm MIME type | application/wasm | Browsers need it for streaming compilation; with a wrong type the loader falls back or fails, depending on the browser. |
| Caching | Revalidate (Cache-Control: no-cache with an ETag) for index.html, bundle.js, chroma_bg.wasm | The build does not add content hashes, so bundle.js keeps the same name across releases. A long immutable cache would serve stale code. |
| Compression | gzip or brotli for .js, .css, .html, .svg | bundle.js is about 57 KB raw and 20 KB gzip. |
404 | Optional custom page | Single-page sites have one real URL. |
10. Keep all application code in .chr
.chr projects expect application code under src/ to be .chr, and the data module, the motion helpers, and the icon helpers are no exception. Because the build no longer runs Node scripts that import your files, nothing needs a plain .js copy.
If a project still has .js files under src/ (for example after migrating a site that used Node scripts), the tools report them:
ERROR chroma/chr-only-extension src/data/site.js
Application source under src/ must use .chr (found src/data/site.js).
WARN [Validate] Legacy .js under src/: src/lib/motion.js — use .chr for Chroma app sourceRename them to .chr and update the imports (the extension is always written out). The app builds either way, because the compiler bundles any module it can reach. You can also lower the rule with "lint": { "chrOnlySeverity": "warning" } in chroma.json while you migrate.
See .chr source format and Linter.
11. Make interaction accessible by default
Static content sites are often judged on accessibility. These costs are small and the reference site pays all of them:
- A skip link as the first focusable element, wired to
#main. aria-expandedon the menu button, bound to a signal.inerton<main>while a full-screen menu is open, so keyboard focus cannot leave the menu.Escapecloses the menu and returns focus to the button.- Lock scroll while the overlay is open and restore it on every close path, including when a breakpoint change resets the animations.
prefers-reduced-motion: no smooth scrolling library, no hidden initial states, no custom cursor.
Rendering gotchas that matter on content sites
Content pages lean on things the framework does differently from the DOM you may be used to. Each row was verified in the engine source.
| You write | What happens | Do this |
|---|---|---|
e("svg", …) | The element is created with document.createElement, so it is in the HTML namespace and does not paint. | Parse the markup with a <template> (tpl.innerHTML = "<svg…>") and pass the resulting node as a child. Create a new node per use; a node can live in one place. |
e("div", { innerHTML: html }) | There is no innerHTML handling. It becomes a plain attribute and no content is inserted. | Build children with e(), or insert trusted markup through a <template> as above. |
render(App, el) on a container with content | The tree is appended after the existing children. | Call el.replaceChildren() first. |
{ download: true }, { inert: true } | true is written as the string "true". false, null, and undefined omit the attribute. Presence-only attributes such as inert still work, but download="true" makes the saved file name true. | Use "" for boolean attributes: { inert: "" }, { download: "" }. |
A function child inside <ul> or <tr> | A reactive child is wrapped in <span style="display: contents">, which is invalid there. | For static lists use array.map(...) directly. Keep reactivity on attributes (class, aria-expanded). See Control flow and Pitfalls. |
| Mutating an array or object in place | Nothing updates; the reference did not change. | Write a new value to the setter. |
Components run once and never re-render, so a mostly static page costs little: only bindings (functions passed as attributes or children) update.
Mistakes to avoid
These were found while reviewing the reference site. None of them breaks the build, which is why they survive.
| Mistake | Cost | Fix |
|---|---|---|
Committing dist/. About 1,000 files were tracked. | Large diffs, noisy history, a 47 MB .git folder. | Add dist/ to .gitignore and build in your deploy step. Keep it tracked only if your host deploys straight from the repository. |
Publishing a legacy mirror. A 45 MB public/TargApps/ folder was copied into dist/, while the rest of the site is about 2 MB. | 45 of the 47 MB uploaded on every deploy. | Host old pages elsewhere, or keep them out of assets/ and public/. |
Loading plugins you do not use. chroma.json listed chroma-style, but the site styles itself with its own CSS. | A request chain before first render (next row), plus two stylesheets. | Remove the plugin from chroma.json and the loader call from main.chr. |
Vendoring all plugins. chroma-fs, chroma-router, and chroma-t2t stayed in plugins/ and shipped to dist/plugins/ (about 500 KB with chroma-style). | Wasted bytes; unused code on the public origin. | Delete plugin folders you do not list in plugins. Also remove stale copies such as a nested plugins/chroma-style/chroma-style/. |
Awaiting plugins before render(). main.chr ran await loadPlugins() first. | The loader fetches chroma.json and each plugin manifest with cache: "no-store", imports the module, and injects CSS before the app mounts. The shell hides the delay, but motion starts later. | Mount first and load optional plugins afterwards, or drop them. |
Template leftovers. A root index.js counter demo, empty pages/ and logic/ folders, and an unused chroma-fs.json. | Confusion about the real entry point. | Delete what chroma.json and index.html do not reference. |
Leftover Node tooling. A package.json, a node_modules/ folder, or a scripts/ folder with postbuild.mjs. | chroma validate warns about it, and the scripts no longer run: chroma build does the work itself. | Delete them; use build plugins and the assets/ and public/ folders instead. |
Originals inside assets/ or public/. Both folders are copied as they are. | Unoptimized originals ship to production. | Keep originals in a folder that is not copied (for example source-assets/). |
Absolute asset and plugin paths. /plugins, /assets/…, /bundle.js. | The site cannot live under a sub-path (for example a GitHub Pages project URL). | Deploy to a domain root. |
Plain .js helpers inside src/. | chroma-lint reports errors and chroma validate warns on every run. | Pattern 10. |
Checklist before you ship
chroma buildends without errors or warnings.chroma previewshowsbundle.jsandchroma_bg.wasmwith 200 and the right MIME type.- With JavaScript disabled, the page shows its full content from the shell.
- With the CDN blocked, the page is readable and has no hidden content.
- With
prefers-reduced-motion: reduce, nothing is hidden and nothing animates. - One
<h1>, a canonical URL, Open Graph image, and valid JSON-LD. dist/is not tracked, and contains no files you do not link to.- The host serves
dist/from the domain root withapplication/wasmand revalidating cache headers. chroma validateandchroma-lint --project .report nothing you did not choose to accept.
Related
- Runtime modes: Portable (Web) and Executable (Desktop)
- CLI reference:
chroma build,chroma preview,chroma dev --static - chroma.json reference:
mode,build,plugins,lint - .chr source format: layout and import rules
- Limitations: no SSR, no keyed lists
- Pitfalls: reactivity mistakes
- Linter and VS Code extension
- Styling: when the optional style plugin is worth it
Plugins
Enable, load, and write Chroma plugins, including the chroma.plugin.json manifest, hook points, and how plugins are vendored into your project, and how they differ from the build plugins that ship inside the CLI.
Legacy JS libraries
Semantic standard and registry for third-party UMD/IIFE scripts in Chroma apps — distinct from @chroma plugins.