From f973230965eacc86c238886c78184200d2f8f849 Mon Sep 17 00:00:00 2001 From: Gerson Umanzor Date: Wed, 29 Apr 2026 09:51:29 -0600 Subject: [PATCH 1/2] fix(web): default Vite dev port to 5173 and auto-wire API URL Both apps previously defaulted to port 3000 (server PORT, web VITE_WEB_PORT), causing a collision when running npm run dev. Default the Vite dev port to 5173 and inject VITE_WEB_API_URL with http://localhost:${PORT} in development mode so the web app reaches the backend out of the box. Production behavior is unchanged (empty base URL, same-origin requests against the server-served frontend). --- apps/web/vite.config.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index fc8e2113..a1c348dd 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -5,14 +5,20 @@ import svgr from 'vite-plugin-svgr'; export default ({ mode }) => { const env = loadEnv(mode, process.cwd(), 'VITE_'); - const PORT = Number(env.VITE_WEB_PORT ?? 3000); + const PORT = Number(env.VITE_WEB_PORT ?? 5173); const HOST = env.VITE_WEB_HOSTNAME || 'localhost'; + const SERVER_PORT = Number(process.env.PORT ?? 3000); + const API_URL = + env.VITE_WEB_API_URL ?? (mode === 'development' ? `http://localhost:${SERVER_PORT}` : ''); return defineConfig({ plugins: [react(), svgr()], css: { postcss: './postcss.config.cjs' }, server: { host: HOST, port: PORT }, - define: { '__APP_VERSION__': JSON.stringify(process.env.npm_package_version) }, + define: { + '__APP_VERSION__': JSON.stringify(process.env.npm_package_version), + 'import.meta.env.VITE_WEB_API_URL': JSON.stringify(API_URL), + }, build: { target: 'esnext', outDir: './dist', From f97df866bf06951a02ded3624fba5c3f4f69590c Mon Sep 17 00:00:00 2001 From: Gerson Umanzor Date: Wed, 29 Apr 2026 09:51:36 -0600 Subject: [PATCH 2/2] docs: correct dev ports, add data dir step, fix knex typo - Document actual dev ports (server 3000, web 5173) and the new zero-config behavior for VITE_WEB_API_URL. - Note that the data/ directory must exist before running migrations, since better-sqlite3 will not create the parent folder. - Fix typo in the migrate:rollback command (npm run -w serverknex -> npm run -w server knex). --- DEVELOPMENT.md | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 94bf9acc..18b8313d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -68,6 +68,12 @@ This will install dependencies for: The development database uses SQLite and is stored in the `data/` directory. +Create the `data/` directory if it does not exist (better-sqlite3 will not create the parent folder and migrations will fail otherwise): + +```bash +mkdir -p data +``` + Run database migrations: ```bash @@ -115,6 +121,8 @@ This uses Turbo to run both apps in parallel: - **Backend server**: http://localhost:3000 (Express API) - **Frontend web app**: http://localhost:5173 (Vite dev server) +The web app automatically points at `http://localhost:3000` for the API in dev mode. + #### Option 2: Run Apps Individually **Backend only:** @@ -122,21 +130,34 @@ This uses Turbo to run both apps in parallel: cd apps/server npm run dev ``` -- Runs on http://localhost:3001 -- Watches for TypeScript changes and auto-restarts +- Runs on http://localhost:3000 by default (override with `PORT`) +- Watches for TypeScript changes and auto-restarts via nodemon **Frontend only:** ```bash cd apps/web npm run dev ``` -- Runs on http://localhost:3000 +- Runs on http://localhost:5173 by default (override with `VITE_WEB_PORT`) - Hot module replacement enabled +- Talks to the API at `http://localhost:${PORT}` in dev (override with `VITE_WEB_API_URL`) + + +### Port and API URL Configuration + +| Variable | Default | Used by | +|----------|---------|---------| +| `PORT` | `3000` | Express server (`apps/server`) | +| `VITE_WEB_PORT` | `5173` | Vite dev server (`apps/web`) | +| `VITE_WEB_HOSTNAME` | `localhost` | Vite dev server bind host | +| `VITE_WEB_API_URL` | `http://localhost:${PORT}` in dev, empty in prod | Web app API base URL | + +If you change the backend `PORT`, set `VITE_WEB_API_URL` to match (e.g. `PORT=4000 VITE_WEB_API_URL=http://localhost:4000 npm run dev`). ### Development Tips -1. **Frontend proxy**: The Vite dev server (port 3000) proxies API requests to the backend (port 3001) +1. **No Vite proxy**: The web app calls the backend directly using `VITE_WEB_API_URL` (see `apps/web/src/api/api.ts`). In production builds it is empty so requests hit the same origin, since the server serves the built frontend. 2. **Hot reload**: Both apps support hot reloading during development 3. **TypeScript**: Changes to TypeScript files trigger automatic recompilation 4. **Shared types**: The `@koinsight/common` package contains types shared between frontend and backend @@ -216,7 +237,7 @@ koinsight/ npm run -w server knex migrate:latest # Rollback last migration -npm run -w serverknex migrate:rollback +npm run -w server knex migrate:rollback # Create a new migration npm run -w server knex migrate:make migration_name @@ -266,6 +287,9 @@ If you need a fresh start: # Delete the database rm data/dev.db +# Make sure the data directory exists +mkdir -p data + # Run migrations npm run -w server knex migrate:latest