99 lines
5.2 KiB
Markdown
99 lines
5.2 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 test # run Vitest test suite
|
|
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
|
|
npm test
|
|
```
|
|
|
|
## 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`. |
|
|
| `VITE_USE_MOCK_POSTS` | Telegram-style resource stream (`/browse`, `/category/:slug`) uses mock posts from `src/mocks/mockPosts.ts` when set to `true` (default while backend `/api/posts` is not yet shipped). Set to `"false"` to hit the real API. See `.unipi/docs/specs/2026-05-25-posts-api-contract.md`. |
|
|
|
|
## 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-CN / en / ja / ko / vi / id / ms 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 test`, `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.
|