wolk/frontend/README.md

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)
• Node >=24.0.0 (for Vite compatibility)
• Go backend running on localhost:8080

Installation

cd frontend
bun install

Development

# 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

# 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)

const { data, isPending, error } = useFiles(path);

Components

interface FileListingProps {
  path: string;
  onFileSelect?: (file: IFile) => void;
}

export function FileListing({ path, onFileSelect }: FileListingProps) {
  // Component logic
}

Routes

export const Route = createFileRoute("/files/$path")({
  component: FileListingPage,
  loader: async ({ params }) => {
    // Pre-fetch data
  },
});

Error Handling

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

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

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
• TanStack Router
• shadcn/ui
• Tailwind CSS
• i18next
• Vite