CLAUDE.md

1# frontend/CLAUDE.md
2 
3Frontend agent guide. Full detail: `frontend/README.md` and the root
4`CONTRIBUTING.md` ("Working on the frontend"). This is the short version.
5 
6## What this is
7React 19 + Ant Design 6 + Vite 8 + TypeScript. The Vite config is
8`vite.config.js` (plain JS). Three bundles, each emitted into
9`internal/web/dist/` and embedded into the Go binary:
10- `index.html` — admin panel SPA (entry `src/main.tsx`; react-router under
11  `/panel`, lazy routes).
12- `login.html` — login + 2FA (`src/entries/login.tsx`).
13- `subpage.html` — public subscription viewer (`src/entries/subpage.tsx`).
14The `@` import alias maps to `src/`.
15 
16## Data flow
17- Server state via TanStack Query (`src/api/`, keys in `src/api/queryKeys.ts`);
18  invalidate on mutation. WebSocket pushes feed the cache
19  (`src/api/websocketBridge.ts`).
20- Local UI state in the page (`useState`); shared concerns via `src/hooks/`.
21  Extend an existing hook before adding a global.
22- Zod (`src/schemas/`) is the single source of truth for the xray config model.
23  Infer types with `z.infer`. Go-side types are mirrored into `src/generated/`
24  by `npm run gen:zod` (`go run ./tools/openapigen`) — do not hand-edit that
25  folder (every file is marked `DO NOT EDIT`).
26- xray domain logic (links, defaults, form<->wire adapters) is pure functions in
27  `src/lib/xray/`. HTTP goes through `HttpUtil` in `src/utils/index.ts`.
28 
29## Rules
30- Ant Design 6 for components; no Tailwind/shadcn (a migration was rolled back).
31  Form *state* runs on React Hook Form (`src/components/form/rhf/`), not Ant
32  Design's `Form` store.
33- Function components + hooks only; no class components.
34- No `//` line comments in committed TS/TSX. HTML comments are fine.
35- TS strict; `no-explicit-any` is an error. Build forms with `useZodForm` +
36  `FormField` from `@/components/form/rhf` (wrap the tree in `FormProvider`);
37  validate through the `zodResolver` or per-field
38  `rules={{ validate: rhfZodValidate(Schema.shape.field) }}` — messages are Zod
39  issue keys resolved via `t()`, never inline `z.string()`. AntD `<Form>` stays
40  only as a layout wrapper. Complex shared config editors (FinalMask / Sniffing /
41  Sockopt) remain AntD-`Form` islands wrapped as value/onChange adapters in
42  `src/lib/xray/forms/fields/`, bound via a `Controller`.
43- New `g.POST`/`g.GET` route => add it to `src/pages/api-docs/endpoints.ts`,
44  then `npm run gen`.
45- i18n strings live in `internal/web/translation/<locale>.json`, NOT under
46  `frontend/`, and are shared with the Go backend. A new English key must be
47  added to every locale. Interpolation here uses single braces `{var}`, not the
48  i18next default `{{var}}`.
49- Persian/Arabic (RTL) users are first-class — isolate code identifiers on their
50  own line when writing Persian text in labels/toasts.
51- Vite is pinned to an exact version (no `^`) — bump deliberately, then verify
52  `npm run dev` AND `npm run build`.
53 
54## Adding a panel route
551. `src/pages/<page>/<Page>.tsx` (kebab folder, PascalCase component).
562. Register in `src/routes.tsx` under `/panel` (lazy import).
573. Add a sidebar link in `src/layouts/AppSidebar.tsx` if it needs nav.
58Only standalone bundles (login/subpage) need a new `.html` + `src/entries/*` +
59`rollupOptions.input` (in `vite.config.js`) + a Go controller route.
60 
61## Commands
62- `npm run dev` (HMR on :5173, proxies to the Go panel on :2053 — start Go first).
63- `npm run typecheck` / `npm run lint` / `npm run test` / `npm run build`.
64- `npm run gen` = `gen:zod` (Go → `src/generated/`) + `gen:api`
65  (`build-openapi.mjs` → `public/openapi.json`).
66- `npm run storybook` (workbench on :6006) / `npm run build-storybook` (CI
67  compile-checks every story). Reusable `src/components/` get a co-located
68  `<Component>.stories.tsx` with `tags: ['autodocs']`; document props via
69  `argTypes` / `parameters.docs` string metadata, never JSDoc.
70- After `npm run build`, RESTART `go run .` (see the XUI_DEBUG gotcha in root
71  CLAUDE.md) before checking the panel.
72