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
| Task | Command |
|---|---|
| Rebuild everything (CSS + JS + embed) | npm run build |
| CSS only | npm run build:css |
| JS only | npm run build:js |
| Embed stylesheet | npm run build:embed |
| Embed player JS | npm run build:embed-player |
| TypeScript type-check (no output) | npm run type-check |
| Watch CSS during development | npm run watch:css |
| Watch JS during development | npm run watch:js |
Run all commands from the repo root (~/ecosystem/musehub).
Source → output mapping
| Asset | Source | Output |
|---|---|---|
| Main stylesheet | src/scss/app.scss |
musehub/templates/musehub/static/app.css |
| Embed stylesheet | src/scss/embed.scss |
musehub/templates/musehub/static/embed.css |
| Main JS bundle | src/ts/app.ts |
musehub/templates/musehub/static/app.js |
| Embed player JS | src/ts/embed-player.ts |
musehub/templates/musehub/static/embed-player.js |
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?
- Run
npm run build(ornpm run build:cssfor CSS only). - 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.