|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Meilisearch-UI is a React-based admin dashboard for managing Meilisearch search engine instances. It supports multi-instance management, internationalization (en/zh), and can be deployed via Docker or static hosting. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +pnpm dev # Start dev server (port 24900) |
| 13 | +pnpm build # Production build with post-processing |
| 14 | +pnpm build:safe # TypeScript check + build |
| 15 | +pnpm lint # Run Biome linter |
| 16 | +pnpm preview # Preview production build |
| 17 | +``` |
| 18 | + |
| 19 | +**Note:** No test framework is configured. |
| 20 | + |
| 21 | +## Architecture |
| 22 | + |
| 23 | +### Tech Stack |
| 24 | +- **Framework:** React 18 + TypeScript + Vite |
| 25 | +- **Routing:** TanStack Router (file-system based) |
| 26 | +- **State:** TanStack Query (server state) + Zustand (client state, persisted to localStorage) |
| 27 | +- **UI:** Mixed - Arco Design, Semi UI, Mantine, NextUI, Radix |
| 28 | +- **Styling:** TailwindCSS + UnoCSS + Sass |
| 29 | +- **i18n:** i18next with custom language detector |
| 30 | + |
| 31 | +### Key Directories |
| 32 | +- `src/routes/` - File-system routing (auto-generates `routeTree.gen.ts`) |
| 33 | +- `src/components/common/` - Reusable UI components |
| 34 | +- `src/components/biz/` - Business logic components |
| 35 | +- `src/components/block/` - Page-level business units |
| 36 | +- `src/hooks/` - Custom hooks (useMeiliClient, useCurrentInstance, etc.) |
| 37 | +- `src/store/` - Zustand store (instances, language settings) |
| 38 | +- `src/locales/{en,zh}/` - Translation JSON files by namespace |
| 39 | + |
| 40 | +### Routing Structure |
| 41 | +Routes use dynamic segments: `/ins/$insID/_layout/index/$indexUID/_layout/documents` |
| 42 | +- `$insID` - Meilisearch instance ID |
| 43 | +- `$indexUID` - Index unique identifier |
| 44 | + |
| 45 | +### State Management |
| 46 | +- **Zustand store** (`src/store/index.ts`): Manages instances list, language, warning page data |
| 47 | +- **TanStack Query**: All Meilisearch API calls with 30s refetch interval |
| 48 | + |
| 49 | +### i18n Namespaces |
| 50 | +common, dashboard, task, key, upload, document, index, instance, header, sys |
| 51 | + |
| 52 | +## Coding Standards |
| 53 | + |
| 54 | +From `.cursorrules`: |
| 55 | +- Code comments in English |
| 56 | +- Git commits in English, follow Conventional Commits (`feat(module): description`) |
| 57 | +- File names: lowercase with hyphens, except TSX components use PascalCase |
| 58 | +- i18n language codes: `zh-CN`, `en-US` format |
| 59 | + |
| 60 | +## Build Configuration |
| 61 | + |
| 62 | +- **Base path:** Configurable via `BASE_PATH` env var |
| 63 | +- **Code splitting:** Manual chunks by node_modules package |
| 64 | +- **Compiler:** SWC for React |
| 65 | +- **Linting:** Biome (tab indentation, auto import sorting) |
| 66 | + |
| 67 | +## Environment Variables |
| 68 | + |
| 69 | +- `BASE_PATH` - Custom base path for deployment |
| 70 | +- `SINGLETON_MODE` - Single instance mode |
| 71 | +- `SINGLETON_HOST` - Host for singleton mode |
| 72 | +- `SINGLETON_API_KEY` - API key for singleton mode |
0 commit comments