0b8c4fe1f7
Some checks failed
Deploy to Frontend Servers / deploy (push) Has been cancelled
User report: after switching to Bahasa Melayu and opening the window to
full width, the header juddered every frame. Root cause was a feedback
loop between the fit measurement and the right-side layout:
* In inline mode the right side renders the favorites label
("Kegemaran Saya") AND no burger button => ~80px wider.
* In burger mode it renders the burger but drops the label => ~80px
narrower.
Available space for the nav was therefore mode-dependent, and the old
60px hysteresis was smaller than that ~80px swing. In a band roughly
1282-1302px (with ms needed=591px) the measurement decided:
burger: needed + 60 <= available_burger -> flip to inline
inline: needed > available_inline -> flip back to burger
(repeat every frame, ResizeObserver re-fires, header shakes)
Two-part fix:
1. Keep the burger button mounted in both modes. When inline it is
pointer-events:none + invisible + aria-hidden=true + tabIndex=-1,
so it stays unclickable but still occupies its 40px box. The
right-side width no longer changes when we flip modes, so the
measurement input stops jumping.
2. Widen the burger->inline hysteresis from 60 to 120 to absorb the
remaining ~80px difference from the favorites label (and per-locale
variations: "My Favorites" vs "Kegemaran Saya" etc). The header
now picks a mode at each width and stays there.
Verified by sweeping the row width across 1100-2200px on the ms locale
in the browser: modeFlips=0 at every previously-broken width, single
clean burger->inline transition once there's room.
Arkie Library Frontend
React + Vite frontend for the ARK Library / ARK database site. The app serves public resource browsing, search, favorites, and an optional admin UI for resource management.
Tech stack
- React 18 + TypeScript
- Vite 5
- React Router
- Tailwind CSS
- 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_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. |
VITE_WALLETCONNECT_PROJECT_ID |
Reown/WalletConnect project ID used by the RainbowKit QR fallback for MetaMask/imToken. TokenPocket QR login does not use this. Required before testing or deploying the fallback scan flow. |
Wallet login notes
Wallet login is used to attach a wallet address to user favorites. The frontend connects an injected wallet (window.ethereum), sends the selected address to POST /api/auth/wallet/login, and stores the returned wallet JWT in localStorage as a simple MVP session mechanism. This keeps the implementation small, but any future XSS vulnerability could expose a wallet session. A more secure future iteration should move wallet sessions to backend-set httpOnly cookies or shorten the token lifetime with refresh-token support.
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— deploysmainto both frontend servers.
Branch and deploy workflow
mainis the deploy branch. Pushing tomaintriggers.gitea/workflows/deploy.yml.terry-stagingexists 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 rsyncsdist/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.