zias
49553233fe
- Complete rewrite of frontend using React 18 + TypeScript in strict mode - Implement TanStack Router for file-based routing matching URL structure - Use TanStack Query for server state management with smart caching - Replace Pinia stores with React Context API for auth and UI state - Adopt Tailwind CSS + shadcn/ui components for consistent styling - Switch from pnpm to Bun for faster package management and builds - Configure Vite to support React, TypeScript, and modern tooling - Create frontend.go with Go embed package for embedding dist/ in binary - Implement comprehensive TypeScript interfaces (strict mode, no 'any' types) - Add dark mode support throughout with Tailwind CSS dark: classes - Set up i18n infrastructure (English translations included) - Remove all Vue 3 code, components, stores, CSS, and assets - Includes 18 new files with ~2000 lines of production-ready code
184 lines
4.2 KiB
Markdown
184 lines
4.2 KiB
Markdown
# WOLK Frontend
|
|
|
|
Modern React 18 SPA for WOLK file browser.
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework:** React 18 + TypeScript
|
|
- **Build Tool:** Vite
|
|
- **Package Manager:** Bun
|
|
- **Routing:** TanStack Router (file-based)
|
|
- **Data Fetching:** TanStack React Query
|
|
- **State Management:** Context API + custom hooks
|
|
- **UI Components:** shadcn/ui (Radix UI + Tailwind CSS)
|
|
- **Styling:** Tailwind CSS
|
|
- **Internationalization:** i18next
|
|
- **Notifications:** react-hot-toast
|
|
- **Date Formatting:** dayjs
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- **Bun** >=1.0 ([install](https://bun.sh))
|
|
- **Node** >=24.0.0 (for Vite compatibility)
|
|
- **Go backend** running on `localhost:8080`
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
cd frontend
|
|
bun install
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Start dev server (http://localhost:5173)
|
|
bun run dev
|
|
|
|
# In another terminal, start Go backend
|
|
cd ..
|
|
go run . --http :8080
|
|
```
|
|
|
|
Dev server automatically proxies `/api` to `http://localhost:8080`.
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Full build with type-checking
|
|
bun run build
|
|
|
|
# Type-check only
|
|
bun run typecheck
|
|
|
|
# Lint
|
|
bun run lint
|
|
bun run lint:fix
|
|
|
|
# Format
|
|
bun run format
|
|
|
|
# Clean dist
|
|
bun run clean
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── api/ # API client modules (files, auth)
|
|
├── components/
|
|
│ ├── ui/ # shadcn UI components
|
|
│ ├── layout/ # Header, Sidebar, LayoutShell
|
|
│ ├── files/ # File-related components
|
|
│ └── modals/ # Dialog components
|
|
├── context/ # React Context (Auth, Layout)
|
|
├── hooks/ # Custom React hooks (useFiles, useAuth, etc.)
|
|
├── routes/ # TanStack Router file-based routes
|
|
├── types/ # TypeScript interfaces
|
|
├── utils/ # Utility functions (format, constants, etc.)
|
|
├── i18n/ # i18next translations
|
|
├── lib/ # Library setup (QueryClient, etc.)
|
|
├── styles/ # Global CSS
|
|
├── main.tsx # Entry point
|
|
└── App.tsx # Root component
|
|
```
|
|
|
|
## Coding Standards
|
|
|
|
See `AGENTS.md` in the project root for detailed style guidelines.
|
|
|
|
### Key Patterns
|
|
|
|
**Custom Hooks (TanStack Query)**
|
|
```tsx
|
|
const { data, isPending, error } = useFiles(path);
|
|
```
|
|
|
|
**Components**
|
|
```tsx
|
|
interface FileListingProps {
|
|
path: string;
|
|
onFileSelect?: (file: IFile) => void;
|
|
}
|
|
|
|
export function FileListing({ path, onFileSelect }: FileListingProps) {
|
|
// Component logic
|
|
}
|
|
```
|
|
|
|
**Routes**
|
|
```tsx
|
|
export const Route = createFileRoute("/files/$path")({
|
|
component: FileListingPage,
|
|
loader: async ({ params }) => {
|
|
// Pre-fetch data
|
|
},
|
|
});
|
|
```
|
|
|
|
**Error Handling**
|
|
```tsx
|
|
const { showError } = useToast();
|
|
try {
|
|
await apiCall();
|
|
} catch (err) {
|
|
if (err instanceof ApiError && err.isCanceled) return; // silent
|
|
showError(err);
|
|
}
|
|
```
|
|
|
|
## API Client
|
|
|
|
The API client is located in `src/api/` with automatic:
|
|
- Token injection in `X-Auth` header
|
|
- Error handling with `ApiError` class
|
|
- Auto-logout on 401
|
|
- Request cancellation support
|
|
|
|
```ts
|
|
import { files as fileAPI } from "@/api";
|
|
|
|
const files = await fileAPI.fetchFiles("/documents");
|
|
```
|
|
|
|
## Translations
|
|
|
|
Translations are in `src/i18n/en.json`. To add support for more languages:
|
|
|
|
1. Create `src/i18n/{lang}.json` with translations
|
|
2. Update `src/i18n/config.ts` to include the new language
|
|
|
|
```ts
|
|
import langTranslations from "./{lang}.json";
|
|
|
|
resources: {
|
|
{lang}: { translation: langTranslations },
|
|
}
|
|
```
|
|
|
|
## Testing
|
|
|
|
Frontend testing infrastructure is not yet configured. Future: Vitest for unit tests, Playwright for e2e.
|
|
|
|
For now, use `bun run typecheck` for type validation.
|
|
|
|
## Contributing
|
|
|
|
1. Follow the code style guidelines in `AGENTS.md`
|
|
2. Use `bun run lint:fix && bun run format` before committing
|
|
3. Ensure `bun run typecheck` passes
|
|
4. Create reusable components in `src/components/`
|
|
5. Use TanStack Query for all server state
|
|
|
|
## Resources
|
|
|
|
- [TanStack React Query](https://tanstack.com/query/latest)
|
|
- [TanStack Router](https://tanstack.com/router/latest)
|
|
- [shadcn/ui](https://ui.shadcn.com)
|
|
- [Tailwind CSS](https://tailwindcss.com)
|
|
- [i18next](https://www.i18next.com)
|
|
- [Vite](https://vitejs.dev)
|