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

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

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:

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` only when set to `"true"`. Leave unset or set to `"false"` to hit the real `/api/posts` API. See `.unipi/docs/specs/2026-05-25-posts-api-contract.md`.

Project layout

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.