6800a8e9b6
Some checks failed
Deploy Staging (terry-wallet-login) / deploy (push) Failing after 40s
The WalletConnect relay (wss://relay.walletconnect.org) is unreliable/blocked in mainland China. Every wallet flow (desktop QR, mobile deeplink, mobile QR) depends on it, so Chinese users see the login button hang forever and the QR code never appears. When RainbowKit's render fails, the whole site goes white because nothing catches the error. Changes: - Add WalletStackErrorBoundary around <RainbowWalletProvider> + modal so RainbowKit init failures no longer blank the entire app. - Hoist <WalletProvider> above the boundary; it only depends on the injected provider, so useWallet keeps working for header / favorites / etc. even when the WC stack is dead. - On mobile, the TP/imToken 'Open Wallet App' button now navigates directly to tpdapp://open / imtokenv2://navigate/DappView with an ?autoLogin=<kind> query, pulling the site into the wallet's in-app browser without ever touching the WC relay. MetaMask still uses the WC path (no equivalent deeplink). - Add AutoInjectedLogin: when the page loads with ?autoLogin=<kind>, wait up to 8s for window.ethereum, then connectInjectedWallet + completeLogin. Strips the param via history.replaceState to avoid re-firing on reload. - Guard against the in-app-browser disconnect/reconnect case: if getInjectedWallet(kind) is already truthy, skip the deeplink and let useWalletConnectLogin's deeplink mode take the injected fast path (avoids TP trying to open TP recursively).
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 verify address ownership for user favorites. The primary stable paths are injected wallets (window.ethereum) and TokenPocket QR callback login. MetaMask/imToken QR login is a RainbowKit/Reown fallback and may be unstable on some China networks.
The current frontend stores the wallet JWT in localStorage as a simple MVP session mechanism. This keeps the implementation small, but any future XSS vulnerability could expose a 30-day 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.