feat: configure router mode and base URL via environment variablesHEADmain

1 files changed, 39 insertions, 3 deletions

diff --git a/README.md b/README.md
index 9299ae6..69b3b7e 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,47 @@
 
 This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
 
+## Environment variables
+
+Copy `.env.example` to `.env` and adjust the values:
+
+```dotenv
+VITE_ROUTER_MODE=hash
+VITE_BASE_URL=/app/
+```
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `VITE_ROUTER_MODE` | `history` | `history` or `hash`; other values fail startup/build. |
+| `VITE_BASE_URL` | `/` | Deployment pathname for assets and routing, such as `/app/`. Must start with a single `/`, without query strings, fragments, whitespace, or backslashes. A trailing `/` is added automatically. |
+
+With `/app/`, the About page is `/app/about` in history mode and
+`/app/#/about` in hash mode. History mode requires the host to serve
+`/app/index.html` for application paths under `/app/`. Hash mode does not
+require a server-side route fallback.
+
+Shell environment variables override `.env` values:
+
+```sh
+VITE_ROUTER_MODE=hash VITE_BASE_URL=/app/ pnpm build
+```
+
+Vite also loads `.env.local`, `.env.[mode]`, and `.env.[mode].local`.
+Mode-specific files override generic files; shell variables have highest priority.
+For example, `pnpm build --mode staging` loads `.env.staging`.
+Environment files are ignored by Git except for `.env.example`.
+Restart the development server after changing variables. Production values are
+embedded during the build; changing server environment variables requires rebuilding.
+Custom frontend variables use the `VITE_` prefix and are read through
+`import.meta.env`. These values are public, so do not put secrets in them.
+See [Vite environment variables](https://vite.dev/guide/env-and-mode).
+
 ## Routing
 
 Routing uses [React Router Data Mode](https://reactrouter.com/start/data/installation).
 `src/route-config.ts` is the single source for page paths, components, titles,
 icons, menu groups, and default expanded groups. It generates the page routes and
-menu data. `src/router.tsx` creates the router with `createBrowserRouter`, and
+menu data. `src/router.tsx` creates the router with `createBrowserRouter` or `createHashRouter`, and
 `src/main.tsx` renders it with `RouterProvider`. `src/App.tsx` configures the
 Spectrum Provider and renders the route `Outlet` inside `BasicLayout`.
 `src/components/layout-basic.tsx` owns the sidebar, top bar, collapse state, and content area,
@@ -65,8 +100,9 @@ absolute `path`, `Component`, and optional `Icon`. Use `children` for menu group
 and `defaultExpanded` to control their initial expansion. Menu groups do not
 change page URLs. Set `hidden: true` to keep a route out of navigation, as with
 the 404 page. Desktop, collapsed, and mobile menus all use this configuration.
-When deploying, configure your host to serve `index.html` for application URLs
-so direct visits and refreshes on nested routes work.
+When deploying in history mode, configure your host to serve `index.html` from
+the configured base directory for application URLs so direct visits and refreshes
+on nested routes work.
 
 Currently, two official plugins are available: