blissful-infra dev

blissful-infra dev starts a development mode that watches for file changes and provides fast feedback loops. It has two distinct modes: project dev mode (for working on a scaffolded app) and template dev mode (for developing the blissful-infra templates themselves).

Usage

# Project dev mode — run from inside a project directory
cd my-app
blissful-infra dev

# Local dev mode (run outside Docker, requires matching JDK)
blissful-infra dev --local

# Template dev mode — run from the repo root
blissful-infra dev --templates <project-name>

Options

Flag	Description
--local	Run the application process locally instead of in Docker. Requires a matching JDK for Spring Boot projects.
--templates <project>	Template development mode: watch packages/cli/templates/ source files and sync changes into a running scaffolded project.

Project dev mode (default)

When run from inside a project directory (one with a blissful-infra.yaml), dev watches source files and reloads the application on changes.

Spring Boot (Docker, with DevTools)

For Spring Boot projects, if a docker-compose.dev.yaml is present (generated by blissful-infra start), the CLI uses Spring Boot DevTools for the fastest possible restart cycle:

1. The backend source is volume-mounted into the container
2. The Gradle incremental compiler (classes -t) runs continuously inside Docker
3. Spring Boot DevTools detects the recompiled classes and restarts the JVM in ~2–3 seconds

cd my-app
blissful-infra dev
# Spring Boot DevTools mode activates automatically

Spring Boot (local)

With --local, the CLI starts the incremental compiler and bootRun directly on your machine — no Docker involved for the app process:

cd my-app/backend
blissful-infra dev --local

The infrastructure services (Kafka, Postgres, Redis) are kept running in Docker. The app connects to them via localhost:9092, localhost:5432, etc.

Other runtimes

For Node.js, Python, and Go projects, dev watches source files, rebuilds on change, and restarts the process. Detection is automatic based on the presence of package.json, go.mod, requirements.txt, etc.

Runtime	Watch paths	Rebuild command
Gradle / Kotlin	src/**/*.kt, src/**/*.java, build.gradle.kts	./gradlew build -x test
Maven	src/**/*.java, pom.xml	./mvnw package -DskipTests
Node.js	src/**/*.ts, src/**/*.tsx, package.json	npm run build
Go	**/*.go, go.mod	go build -o app .
Python	**/*.py, requirements.txt	(no compilation needed)

Changes are debounced by 500ms to avoid triggering multiple rebuilds on rapid saves.

Template dev mode (--templates)

This mode is for contributing to blissful-infra or customizing the starter templates. It bridges the gap between editing template source files and seeing the result live in a running app.

Workflow

Step 1 — Scaffold a development project (once):

blissful-infra start dev-app

Step 2 — Start template dev mode (leave running in a terminal):

blissful-infra dev --templates dev-app

Step 3 (Spring Boot backend only) — Start the incremental Kotlin compiler in a separate terminal:

cd dev-app/backend && ./gradlew classes -t

Now edit any file under packages/cli/templates/react-vite/src/ or packages/cli/templates/spring-boot/src/. The changes are:

1. Processed for template variable substitution ({{PROJECT_NAME}} → dev-app, etc.)
2. Written to the corresponding path in dev-app/frontend/src/ or dev-app/backend/src/
3. Picked up automatically — Vite HMR updates the browser for frontend changes, Spring DevTools restarts the JVM for backend changes

What template dev mode does internally

• Stops the Docker frontend container (dev-app-frontend) so it doesn’t hold port 3000
• Starts a Vite dev server natively in dev-app/frontend/ for HMR
• Patches nginx.conf to route frontend traffic to host.docker.internal:3000 (the native Vite server) instead of the Docker container
• Reloads nginx so the change takes effect immediately
• Watches packages/cli/templates/spring-boot/src/ and packages/cli/templates/react-vite/src/ with chokidar (no polling — native filesystem events)

On Ctrl+C, template dev mode restores nginx.conf to point back at the Docker frontend container.

Template variable substitution

Template files use {{PROJECT_NAME}} and conditional blocks that are resolved when syncing:

{{PROJECT_NAME}}         → replaced with the project name
{{#IF_POSTGRES}}...{{/IF_POSTGRES}}   → included only when database includes postgres
{{#IF_REDIS}}...{{/IF_REDIS}}         → included only when database includes redis

These substitutions are applied every time a file is synced to the dev project, so you can freely use template variables in template source files.

Cleanup

# Stop and remove the dev project
docker compose -f dev-app/docker-compose.yaml down -v
rm -rf dev-app