how to develop live
This commit is contained in:
@@ -8,8 +8,7 @@ Quick start:
|
||||
|
||||
2. Open **http://localhost:5173** — the page calls **`/api/health`** and **`/api/groups`** through the Vite proxy.
|
||||
|
||||
3. Read the step-by-step notes under **`doc/`**: [doc/README.md](doc/README.md).
|
||||
|
||||
3. Read the step-by-step notes under **`doc/`**: [doc/README.md](doc/README.md). For everyday coding (Vite HMR, restarting Swift/Vapor), see [doc/tutorial-development-live-reload.md](doc/tutorial-development-live-reload.md).
|
||||
Ports are overridable via **`.env`** (see **`.env.example`**).
|
||||
|
||||
Kubernetes deployment manifests (`Deployment`, `Service`, `StatefulSet`, `Ingress`) live in **`k8s/`** — see **`k8s/README.md`** and **`doc/step-08-kubernetes.md`**.
|
||||
|
||||
@@ -12,3 +12,11 @@ Each file records **one concrete step** taken when scaffolding this repository.
|
||||
| 6 | [step-06-docker-compose.md](step-06-docker-compose.md) | Root `docker-compose.yml`, env vars, service wiring |
|
||||
| 7 | [step-07-next-steps.md](step-07-next-steps.md) | Roadmap toward full Fusion parity |
|
||||
| 8 | [step-08-kubernetes.md](step-08-kubernetes.md) | Kubernetes Deployments/Services/Ingress manifests |
|
||||
|
||||
---
|
||||
|
||||
## Tutorials
|
||||
|
||||
| Document | Topic |
|
||||
| --- | --- |
|
||||
| [tutorial-development-live-reload.md](tutorial-development-live-reload.md) | Local workflows, **Vite HMR**, automating Swift **restarts** (“live reload”), Docker vs hybrid |
|
||||
@@ -0,0 +1,150 @@
|
||||
# Tutorial — Local development and live reload
|
||||
|
||||
This guide explains how to work on SFusion day to day, and what kind of **live reload** / **hot reload** you can expect (and what you cannot).
|
||||
|
||||
---
|
||||
|
||||
## 1. What actually reloads?
|
||||
|
||||
| Part of the stack | Live / hot reload | Notes |
|
||||
| --- | --- | --- |
|
||||
| **React + Vite** (`frontend/`) | **Yes — HMR** | Vite pushes updated modules to the browser; state is preserved where React Fast Refresh allows it. |
|
||||
| **Vapor backend** (`backend/`) | **No true hot reload** | Swift compiles to a native binary. Any change to server code requires **rebuild + process restart**. You can **automate** restarts with file watchers (below). |
|
||||
| **PostgreSQL schema** | **No** | Fluent runs migrations when the app starts (`AUTO_MIGRATE` / dev). Schema changes are deliberate migration steps, not hot-patched. |
|
||||
|
||||
So: **frontend feels like live reload** out of the box; **backend is save → rebuild → rerun**, optionally scripted.
|
||||
|
||||
---
|
||||
|
||||
## 2. Recommended setup for the best DX
|
||||
|
||||
Run **three processes** on the host (not inside the backend container), and only use Docker for Postgres if you want:
|
||||
|
||||
1. **PostgreSQL** — `docker compose up postgres` **or** a local Postgres listening on `5432`.
|
||||
2. **Backend** — `swift run Run` from **`backend/`**, with `DATABASE_*` / `AUTO_MIGRATE` set.
|
||||
3. **Frontend** — `npm run dev` from **`frontend/`**, with Vite proxying `/api` to the backend.
|
||||
|
||||
That way you get **instant HMR on the UI** and **incremental Swift builds** between short restarts.
|
||||
|
||||
---
|
||||
|
||||
## 3. Database
|
||||
|
||||
### Option A — Postgres in Docker
|
||||
|
||||
```bash
|
||||
docker compose up postgres
|
||||
```
|
||||
|
||||
Use the same credentials as in `docker-compose.yml` (defaults: user/database/password **`sfusion`**) and point the backend at **`localhost:5432`**.
|
||||
|
||||
### Option B — Postgres installed locally
|
||||
|
||||
Create database and users to match your `DATABASE_*` environment variables.
|
||||
|
||||
---
|
||||
|
||||
## 4. Backend (Vapor / Swift)
|
||||
|
||||
From **`backend/`**:
|
||||
|
||||
```bash
|
||||
export DATABASE_HOST=localhost
|
||||
export DATABASE_PORT=5432
|
||||
export DATABASE_USERNAME=sfusion
|
||||
export DATABASE_PASSWORD=sfusion
|
||||
export DATABASE_NAME=sfusion
|
||||
export AUTO_MIGRATE=true
|
||||
|
||||
swift run Run
|
||||
```
|
||||
|
||||
The server listens on **`0.0.0.0:8080`** by default (`configure.swift`).
|
||||
|
||||
### “Live reload” for Swift means auto-restart on save
|
||||
|
||||
There is **no** Swift equivalent of Vite’s HMR at the HTTP layer. Practical approach: watch **`Sources/**/*.swift`** and **`Package.swift`**, then **build and run again**.
|
||||
|
||||
**[`entr`](http://eradman.com/entrproject/)** (e.g. `brew install entr`):
|
||||
|
||||
With `DATABASE_*` and `AUTO_MIGRATE` exported in your shell beforehand:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
(find Sources -name '*.swift'; echo Package.swift) | entr -r swift run Run
|
||||
```
|
||||
|
||||
`swift run` performs an incremental build when needed and then launches **`Run`**; **`entr -r`** restarts that whole step after each tracked file change.
|
||||
|
||||
**Note:** SPM may place binaries under **`.build/*/debug/`** depending on triple; **`swift run`** always runs the right product.
|
||||
|
||||
**[`watchexec`](https://github.com/watchexec/watchexec)** is a good cross-platform variant:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
watchexec -e swift -w Sources -w Package.swift --restart -- swift run Run
|
||||
```
|
||||
|
||||
(Export the same `DATABASE_*` and `AUTO_MIGRATE` in your shell.)
|
||||
|
||||
### IDE
|
||||
|
||||
Opening **`backend/Package.swift`** in Xcode (or similar) gives incremental builds plus one-click Run; restarting the debugger is still the “reload.”
|
||||
|
||||
---
|
||||
|
||||
## 5. Frontend — real hot module replacement
|
||||
|
||||
From **`frontend/`**:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
export VITE_API_PROXY_TARGET=http://127.0.0.1:8080
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open **http://localhost:5173**. Edits under **`frontend/src`** update in the browser via **Vite HMR**.
|
||||
|
||||
`vite.config.ts` proxies **`/api`** to `VITE_API_PROXY_TARGET`; keep that URL pointed at whichever host runs Vapor (**`127.0.0.1:8080`** when the backend runs on your machine).
|
||||
|
||||
---
|
||||
|
||||
## 6. All-in-docker vs hybrid
|
||||
|
||||
### Full `docker compose up`
|
||||
|
||||
When the frontend service bind-mounts **`./frontend`**, **`npm run dev`** in the container still supports **Vite HMR**: the browser talks to the mapped port (**5173**), and edits on disk sync through the volume.
|
||||
|
||||
Changing **Swift** in **`backend/`** requires **rebuilding the backend image** (e.g. `docker compose build backend` or `up --build`). There is **no hot reload inside the Swift container** unless you add your own watcher and dev image.
|
||||
|
||||
### Hybrid (recommended for backend-heavy changes)
|
||||
|
||||
| Service | Where to run |
|
||||
| --- | --- |
|
||||
| Postgres | Docker Compose or native |
|
||||
| Backend | **`cd backend && swift run Run`** (optionally **`entr`/`watchexec`**) |
|
||||
| Frontend | **`cd frontend && npm run dev`** with proxy → **`http://127.0.0.1:8080`** |
|
||||
|
||||
---
|
||||
|
||||
## 7. Environment quick reference
|
||||
|
||||
| Variable | Typical local value |
|
||||
| --- | --- |
|
||||
| `DATABASE_HOST` | `localhost` |
|
||||
| `DATABASE_PORT` | `5432` |
|
||||
| `DATABASE_USERNAME` / `DATABASE_PASSWORD` / `DATABASE_NAME` | `sfusion` (match `docker-compose.yml`) |
|
||||
| `AUTO_MIGRATE` | `true` in development |
|
||||
| `VITE_API_PROXY_TARGET` | `http://127.0.0.1:8080` |
|
||||
| `PORT` | `8080` (backend) |
|
||||
|
||||
Inside Docker’s backend service, **`DATABASE_HOST`** is **`postgres`**; on the Mac host it must be **`localhost`**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Summary
|
||||
|
||||
- Treat **frontend** development as **Vite HMR**.
|
||||
- Treat **backend** development as **recompile + rerun**, optionally wrapped with **`entr`** or **`watchexec`**.
|
||||
- For the fastest iteration across layers, prefer **Docker or local Postgres + local Swift + local Vite** over rebuilding the Swift image on every tweak.
|
||||
Reference in New Issue
Block a user