diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 42 |
1 files changed, 39 insertions, 3 deletions
@@ -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: |