hot-reload

Hot Reload Behavior

How file changes trigger rebuilds in development.

Quick Start

# Terminal 1: Start services
just dev

# Terminal 2: Watch for changes (REQUIRED for frontend hot reload)
just watch-templates

Architecture Overview

Pre-bundled frontend: astro/dist/ is committed to git. No Vite dev server at runtime.

Frontend (chokidar + Astro Build)

File watching is handled by just watch-templates running in a separate terminal.

Rebuild Process

1. chokidar detects file change
2. Triggers pnpm build (Astro)
3. Output written to astro/dist/
4. nginx serves updated files immediately (bind mount)
5. Browser refresh shows changes

Prerequisite: just watch-templates must be running.

Manual Build

If watch isn't running:

just build-astro

Committing Changes

After frontend changes, commit both source and dist:

git add astro/src/ astro/dist/
git commit -m "feat: Update frontend styles"

Backend (uvicorn --reload)

uvicorn watches Python files automatically.

No action needed - uvicorn handles Python file watching.

Jinja2 Templates

Templates in astro/dist/ auto-reload on each request:

• No container restart
• No build step
• Just refresh browser

Templates in astro/dist/layouts/ (Astro-built wrapper):

• Rebuild with just build-astro
• Or use just watch-templates

Troubleshooting

Changes Don't Appear

1. Check watch is running:

   docker compose exec -T frontend pgrep -f "chokidar"
   

   If no output: just watch-templates in new terminal

2. Check for build errors:

   docker compose logs frontend --tail=20
   

3. Force rebuild:

   just build-astro
   

4. Verify dist/ is updated:

   ls -la astro/dist/
   

CSS Not Updating

CSS is compiled by Astro, not served directly.

1. Verify astro/src/styles/global.css exists
2. Check just watch-templates is running
3. Look for astro/dist/_astro/*.css file
4. Hard refresh browser (Cmd+Shift+R)

React Islands Not Updating

Islands are built separately:

# Check if islands exist
ls astro/dist/islands/

# Manual rebuild
docker compose exec astro pnpm build:islands

Python Changes Not Reloading

1. Check container is running:

   docker compose ps backend
   

2. Check logs for reload:

   docker compose logs backend --tail=20
   

3. Restart if stuck:

   docker compose restart backend
   

Verification

Use the workflow-verifier agent or /workflow-check command:

/workflow-check

This tests all hot reload paths and reports status.

File Type Quick Reference

Common Issues

Key Difference from Traditional Dev Servers

There is no Vite dev server running at runtime. The workflow is:

1. Edit files in astro/src/
2. Watch process (or manual build) compiles to astro/dist/
3. nginx serves pre-built files from the bind-mounted directory
4. No HMR - full page refresh needed

This architecture means:

• Simpler runtime (no dev server process)
• astro/dist/ is committed to git
• CI uses pre-committed dist (no build step)
• Production-like serving even in development