96 lines
3.4 KiB
Markdown
96 lines
3.4 KiB
Markdown
|
# Arkie Library Frontend
|
||
|
|
|
||
|
|
React + Vite frontend for the ARK Library / ARK database site. The app serves public resource browsing, search, favorites, wallet login UI, and an optional admin UI for resource management.
|
||
|
|
|
||
|
|
## Tech stack
|
||
|
|
|
||
|
|
- React 18 + TypeScript
|
||
|
|
- Vite 5
|
||
|
|
- React Router
|
||
|
|
- Tailwind CSS
|
||
|
|
- RainbowKit / Wagmi / Viem for wallet connection
|
||
|
|
- Gitea Actions deploy workflow on `main`
|
||
|
|
|
||
|
|
## Quick start
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm ci
|
||
|
|
npm run dev
|
||
|
|
```
|
||
|
|
|
||
|
|
Local dev server: <http://localhost:5173>
|
||
|
|
|
||
|
|
In development, Vite proxies these paths to the backend at `http://127.0.0.1:8080`:
|
||
|
|
|
||
|
|
- `/api`
|
||
|
|
- `/uploads`
|
||
|
|
|
||
|
|
If `VITE_API_URL` is set, API calls use that absolute base URL instead.
|
||
|
|
|
||
|
|
## Useful commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm run dev # start Vite dev server
|
||
|
|
npx tsc --noEmit # TypeScript check; CI requires this
|
||
|
|
npm run format:check # Prettier check; CI requires this
|
||
|
|
npm run format # format source files
|
||
|
|
npm run build # production build to dist/
|
||
|
|
npm run preview # preview built app locally
|
||
|
|
```
|
||
|
|
|
||
|
|
Before pushing, run at least:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npx tsc --noEmit
|
||
|
|
npm run format:check
|
||
|
|
```
|
||
|
|
|
||
|
|
## Environment variables
|
||
|
|
|
||
|
|
Create a local `.env` only when needed. Do not commit secrets. See `.env.example` for a template.
|
||
|
|
|
||
|
|
| Variable | Purpose |
|
||
|
|
| --- | --- |
|
||
|
|
| `VITE_API_URL` | API/upload origin. Empty means same-origin and Vite dev proxy handles local `/api` and `/uploads`. Production deploy currently uses `https://api.ark-library.com`. |
|
||
|
|
| `VITE_WALLETCONNECT_PROJECT_ID` | Reown / WalletConnect project id. Needed for QR/mobile wallet connection. |
|
||
|
|
| `VITE_DISABLE_ADMIN` | When set to `"true"`, public build redirects admin routes away. Production public deploy sets this to `"true"`. |
|
||
|
|
| `VITE_ADMIN_ONLY` | When set to `"true"`, builds the admin-only app entry instead of the public app. |
|
||
|
|
| `VITE_ADMIN_UI_PREFIX` | Optional admin UI base path. If absent in admin-only mode, code uses the secret prefix from `src/adminPaths.ts`. |
|
||
|
|
|
||
|
|
## Project layout
|
||
|
|
|
||
|
|
```text
|
||
|
|
src/
|
||
|
|
main.tsx # app entry; switches public vs admin-only build
|
||
|
|
App.tsx # public app + optional admin routes
|
||
|
|
AppAdminOnly.tsx # admin-only app entry
|
||
|
|
api.ts # fetch helpers and shared API types
|
||
|
|
i18n.tsx # zh-TW / zh-CN / en copy dictionary
|
||
|
|
adminPaths.ts # admin UI prefix logic
|
||
|
|
adminRouteTree.tsx # admin routes
|
||
|
|
components/ # reusable public components
|
||
|
|
layouts/ # public/admin layout shells
|
||
|
|
pages/ # public pages
|
||
|
|
pages/admin/ # admin pages
|
||
|
|
utils/ # formatting/display helpers
|
||
|
|
```
|
||
|
|
|
||
|
|
Important config files:
|
||
|
|
|
||
|
|
- `vite.config.ts` — Vite build and local backend proxy.
|
||
|
|
- `tailwind.config.js` — ARK color palette and font stack.
|
||
|
|
- `Dockerfile` / `nginx.conf` — container build and static SPA serving.
|
||
|
|
- `.gitea/workflows/deploy.yml` — deploys `main` to both frontend servers.
|
||
|
|
|
||
|
|
## Branch and deploy workflow
|
||
|
|
|
||
|
|
- `main` is the deploy branch. Pushing to `main` triggers `.gitea/workflows/deploy.yml`.
|
||
|
|
- `terry-staging` exists as a staging/work branch for later work.
|
||
|
|
- The deploy workflow runs `npm ci`, `npx tsc --noEmit`, `npm run format:check`, `npm run build`, then rsyncs `dist/` to both frontend servers and verifies matching checksums.
|
||
|
|
|
||
|
|
See also:
|
||
|
|
|
||
|
|
- `AGENTS.md` — instructions for AI coding agents.
|
||
|
|
- `docs/workflow.md` — recommended day-to-day workflow.
|
||
|
|
- `docs/deploy.md` — deploy details and troubleshooting.
|