Frontend Asset Builds

All CSS and TypeScript is compiled from source — never edit app.css or app.js directly.

Source vs output

Source files live in src/ at the repo root. Compiled artifacts land in static/.

src/
  ts/          ← TypeScript source (input to esbuild)
    app.ts
    musehub.ts
    pages/*.ts
  scss/        ← SCSS source (input to sass)
    app.scss
    embed.scss
    _*.scss    ← partials, imported by app.scss

musehub/templates/musehub/static/
  app.js       ← compiled output (do not edit)
  app.css      ← compiled output (do not edit)
  embed.css    ← compiled output (do not edit)
  alpinejs.min.js
  htmx.min.js
  vendor/

Quick reference

Run all commands from the repo root (~/ecosystem/musehub).

Source → output mapping

src/scss/app.scss imports all SCSS partials from src/scss/_*.scss. Add new partials there, not inline.

When to rebuild

Rebuild whenever you change any .scss or .ts file. The server serves the compiled files directly — it does not compile on the fly.

npm run build also writes musehub/templates/musehub/static/.cache-id with a timestamp. The base template reads this file to generate the ?v=<timestamp> query string on every static asset URL, which busts the browser cache automatically after each rebuild.

CSS not updating in the browser?

1. Run npm run build (or npm run build:css for CSS only).
2. Hard-refresh: Cmd+Shift+R (macOS) / Ctrl+Shift+R (Linux/Windows).

If the page still looks wrong, check that you rebuilt to the right output path:

musehub/templates/musehub/static/app.css   ✅ correct
musehub/templates/musehub/static/css/app.css  ❌ wrong — served at /static/css/app.css, not /static/app.css

Development workflow

Open two terminals:

# Terminal 1 — watch CSS
npm run watch:css

# Terminal 2 — watch JS
npm run watch:js

Changes to any .scss or .ts file are compiled instantly. Because the watch builds omit the cache-id update, you may need an occasional hard-refresh during development.

Prerequisites

Node.js and the dev dependencies must be installed:

npm install   # installs esbuild, sass, typescript — runs from repo root

sass and esbuild run on the host (not inside Docker). The compiled output files are bind-mounted into the container via docker-compose.override.yml, so the server picks up the new files without a restart.