From 6b1b4285fa93d25cf644dc69ed165fb166bc0f98 Mon Sep 17 00:00:00 2001 From: Jeroen Ubbink Date: Thu, 25 Jun 2026 10:54:26 +0200 Subject: [PATCH] docs(ui): document dev/build/serve workflow; make missing-bundle warning actionable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ui/README.md was still stock create-next-app boilerplate. Replace it with the real story: the UI is a Next.js static export served by FastAPI from ui_out/, the two-process dev loop (backend :8000 + `make ui-dev` :3000 with hot reload, auto- targeting :8000), the build/integration commands, and the cross-origin CORS note. Also make the "ui_out not found" startup warning actionable — it now points to `make ui-build` / `make ui-dev` instead of silently saying it skipped serving. Co-Authored-By: Claude Opus 4.8 --- routstr/core/main.py | 5 +++- ui/README.md | 56 +++++++++++++++++++++++++------------------- 2 files changed, 36 insertions(+), 25 deletions(-) diff --git a/routstr/core/main.py b/routstr/core/main.py index ce801df7..3bbda7fa 100644 --- a/routstr/core/main.py +++ b/routstr/core/main.py @@ -369,7 +369,10 @@ if UI_DIST_PATH.exists() and UI_DIST_PATH.is_dir(): else: logger.warning( - f"UI dist directory not found at {UI_DIST_PATH}, skipping static file serving" + "UI dist directory not found at %s; serving API only. Run `make ui-build` " + "to build the static UI served from here, or `make ui-dev` for the Next.js " + "dev server with hot reload on :3000 (it targets this backend on :8000).", + UI_DIST_PATH, ) @app.get("/", include_in_schema=False) diff --git a/ui/README.md b/ui/README.md index e215bc4c..b7280812 100644 --- a/ui/README.md +++ b/ui/README.md @@ -1,36 +1,44 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# Routstr node admin UI -## Getting Started +A [Next.js](https://nextjs.org) app (App Router, **static export**) that provides the +admin dashboard for a `routstr-core` node: login, settings, providers, balances, +transactions, usage, and logs. -First, run the development server: +There is no separate web server in production. `next build` produces a fully static +export (`next.config.ts` sets `output: 'export'`), and the FastAPI backend serves it +directly from `../ui_out/` (see `routstr/core/main.py`). So the UI and the API are +served from the **same origin** in production. -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev -``` +## Developing the UI (hot reload) -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +The everyday loop runs two processes side by side — you do **not** rebuild the static +export while developing: -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +1. Start the backend on `:8000` — from the repo root: `make docker-up` (or + `uvicorn routstr.core.main:app --reload`). +2. Start the Next.js dev server on `:3000` — from the repo root: `make ui-dev` + (or `cd ui && pnpm dev`). Edits hot-reload instantly. -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +Open http://localhost:3000. With no `NEXT_PUBLIC_API_URL` set, the UI falls back to +`http://127.0.0.1:8000` in development (see `lib/api/services/configuration.ts`), so it +talks to the local backend out of the box. -## Learn More +Because dev is cross-origin (`:3000` → `:8000`), it relies on the backend's CORS +allowing the UI origin. The default `cors_origins` is `["*"]`; if you tighten CORS, +keep `http://localhost:3000` allowed for development. -To learn more about Next.js, take a look at the following resources: +## Building the integrated/static UI (what production serves) -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +To produce the bundle that FastAPI serves from `../ui_out/`: -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +- `make ui-build` — builds with local Node/pnpm (`scripts/build-ui.sh`), then moves + `ui/out/*` to `../ui_out/`. +- `make ui-build-docker` — same, but inside Docker (no local Node needed). -## Deploy on Vercel +`NEXT_PUBLIC_*` variables are read from the repo-root `.env` at build time and baked in. +For a same-origin deployment leave `NEXT_PUBLIC_API_URL` empty (relative paths); the UI +uses `window.location.origin` at runtime. After building, start the backend and open +http://localhost:8000 — the dashboard is served at `/` and `/admin`. -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. - -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +If `../ui_out/` does not exist, the backend logs a warning at startup and serves the API +only (hitting a UI route returns a small JSON fallback instead of the dashboard).