3x-ui/frontend/CLAUDE.md

frontend/CLAUDE.md

Frontend agent guide. Full detail: frontend/README.md and the root CONTRIBUTING.md ("Working on the frontend"). This is the short version.

What this is

React 19 + Ant Design 6 + Vite 8 + TypeScript. The Vite config is vite.config.js (plain JS). Three bundles, each emitted into internal/web/dist/ and embedded into the Go binary:

• index.html — admin panel SPA (entry src/main.tsx; react-router under /panel, lazy routes).
• login.html — login + 2FA (src/entries/login.tsx).
• subpage.html — public subscription viewer (src/entries/subpage.tsx). The @ import alias maps to src/.

Data flow

• Server state via TanStack Query (src/api/, keys in src/api/queryKeys.ts); invalidate on mutation. WebSocket pushes feed the cache (src/api/websocketBridge.ts).
• Local UI state in the page (useState); shared concerns via src/hooks/. Extend an existing hook before adding a global.
• Zod (src/schemas/) is the single source of truth for the xray config model. Infer types with z.infer. Go-side types are mirrored into src/generated/ by npm run gen:zod (go run ./tools/openapigen) — do not hand-edit that folder (every file is marked DO NOT EDIT).
• xray domain logic (links, defaults, form<->wire adapters) is pure functions in src/lib/xray/. HTTP goes through HttpUtil in src/utils/index.ts.

Rules

• Ant Design 6 for components; no Tailwind/shadcn (a migration was rolled back). Form state runs on React Hook Form (src/components/form/rhf/), not Ant Design's Form store.
• Function components + hooks only; no class components.
• Comments in committed TS/TSX: 2 lines MAX per comment block, spent on the why a name cannot hold (same rule as root CLAUDE.md). HTML comments are fine.
• TS strict; oxlint's typescript/no-explicit-any is an error. Build forms with React Hook Form's useForm + FormField from @/components/form/rhf (wrap the tree in FormProvider) and validate each field with rules={{ validate: rhfZodValidate(Schema.shape.field) }} — messages are Zod issue keys resolved via t(), never inline z.string(). A whole-form zodResolver is only for a form that submits one schema. AntD <Form> stays only as a layout wrapper. Complex shared config editors (FinalMask / Sniffing / Sockopt) remain AntD-Form islands wrapped as value/onChange adapters in src/lib/xray/forms/fields/, bound via a Controller.
• New g.POST/g.GET route => add it to src/pages/api-docs/endpoints.ts, then npm run gen.
• i18n strings live in internal/web/translation/<locale>.json, NOT under frontend/, and are shared with the Go backend. A new English key must be added to every locale. Interpolation here uses single braces {var}, not the i18next default {{var}}.
• Persian/Arabic (RTL) users are first-class — isolate code identifiers on their own line when writing Persian text in labels/toasts.
• Vite is pinned to an exact version (no ^) — bump deliberately, then verify npm run dev AND npm run build.

Adding a panel route

1. src/pages/<page>/<Page>.tsx (kebab folder, PascalCase component).
2. Add it to src/routes/panelRoutes.tsx. The router, the sidebar, the page title and the command palette all read that one list; src/test/navigation-contract.test.tsx holds it to the router and to the translation bundle. Only standalone bundles (login/subpage) need a new .html + src/entries/* + rollupOptions.input (in vite.config.js) + a Go controller route.

Commands

• npm run dev (HMR on :5173, proxies to the Go panel on :2053 — start Go first).
• npm run typecheck / npm run lint / npm run test / npm run build.
• npm run gen = gen:zod (Go → src/generated/) + gen:api (build-openapi.mjs → public/openapi.json).
• npm run storybook (workbench on :6006) / npm run build-storybook (CI compile-checks every story). Reusable src/components/ get a co-located <Component>.stories.tsx with tags: ['autodocs']; document props via argTypes / parameters.docs string metadata, never JSDoc.
• After npm run build, RESTART go run . (see the XUI_DEBUG gotcha in root CLAUDE.md) before checking the panel.