Skip to content

Frontend Development

React 18 + TypeScript + Material-UI v6 + Vite frontend.

Quick Start

Text Only
1
```bash

Install dependencies

task install-frontend

Start development server

task run-frontend

Visit: http://localhost:5173

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
## Tech Stack

- **React 18** - UI library
- **TypeScript** - Type safety
- **Vite** - Build tool & dev server
- **Material-UI v6** - Component library
- **TanStack React Query** - Server state
- **React Router** - Routing
- **Auto-generated API Client** - Type-safe API calls

## Project Structure
frontend/src/ ├── pages/ # Route components ├── components/ # Reusable UI components │ ├── ui/ # Unified component system │ ├── Articles/ # Article components │ ├── Home/ # Landing page sections │ └── ... ├── hooks/ │ └── api/ # React Query hooks for API calls ├── client/ # Auto-generated TypeScript API client ├── theme/ # Material-UI theme configuration ├── context/ # React Context providers ├── utils/ # Utility functions ├── App.tsx # Main app with routing └── main.tsx # Entry point
Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
## Development Workflow

### Start Development

    ```bash
# Terminal 1: Backend
task run-backend

# Terminal 2: Frontend
task run-frontend

# Access: http://localhost:5173

After Backend API Changes

CRITICAL: Always regenerate TypeScript client:

Text Only
1
```bash

task frontend:generate-client `` This updatesfrontend/src/client/` with latest API types.

Adding New Page

  1. Create page in frontend/src/pages/: typescript // frontend/src/pages/MyPage.tsx import { DashboardLayout } from '@/components/ui'; const MyPage: React.FC = () => { return ( <DashboardLayout> <h1>My Page</h1> </DashboardLayout> ); }; export default MyPage;

  2. Add route in App.tsx:

    TypeScript
    1
2
3
    import MyPage from './pages/MyPage';

<Route path="dashboard/my-page" element={<MyPage />} />

  3. Add navigation in DashboardLayout.tsx (if needed)

Adding New Component

Use unified components from @/components/ui:

TypeScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import { 
  ModernCard, 
  StandardButton, 
  PageHeader 
} from '@/components/ui';

const MyComponent = () => {
  return (
    <ModernCard title="Card Title" icon={<Icon />}>
      <StandardButton onClick={handleClick}>
        Click Me
      </StandardButton>
    </ModernCard>
  );
};

Component library

API Integration

Using React Query Hooks

TypeScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { useArticles } from '@/hooks/api/useArticles';

const Component = () => {
  const { data: articles, isLoading, error } = useArticles();

  if (isLoading) return <Loading />;
  if (error) return <Error />;

  return (
    <div>
      {articles.map(article => (
        <ArticleCard key={article.id} article={article} />
      ))}
    </div>
  );
};

Creating API Hooks

After generating client:

TypeScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// frontend/src/hooks/api/useMyFeature.ts
import { useQuery } from '@tanstack/react-query';
import { MyService } from '@/client';

export const useMyFeature = () => {
  return useQuery({
    queryKey: ['myFeature'],
    queryFn: MyService.getMyFeature,
  });
};

Theme System

Dark Mode

Automatically supported - toggle available in UI.

Using Theme

TypeScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import { useTheme } from '@mui/material';

const Component = () => {
  const theme = useTheme();

  return (
    <Box sx={{
      bgcolor: theme.palette.background.paper,
      color: theme.palette.text.primary,
      padding: theme.spacing(3),
    }}>
      Content
    </Box>
  );
};

Responsive Design

TypeScript
1
2
3
4
5
6
<Box sx={{
  display: { xs: 'block', md: 'flex' },
  padding: { xs: 2, md: 3 }
}}>
  Content
</Box>

Building for Production

Text Only
1
```bash

Build frontend

cd frontend npm run build

Output in: frontend/dist/

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
## Available Task Commands

    ```bash
# Development
task run-frontend          # Start dev server
task install-frontend      # Install dependencies
task frontend:generate-client  # Generate API client
task frontend:build        # Build for production
task frontend:preview      # Preview production build

# Testing
task frontend:test         # Run tests
task frontend:test-watch   # Watch mode

# Linting
task frontend:lint         # Check linting
task frontend:lint-fix     # Auto-fix

Pages by Tier

All Tiers

  • Home (landing page)
  • Login, SignUp
  • Dashboard
  • My Articles (Create, Edit, View, List)
  • Profile
  • Password Reset flow
  • Terms, Privacy
  • 404, 500 error pages

Top G & AI Velocity

  • Billing (subscription management)
  • Analytics dashboard
  • Integrations
  • Payment Success/Cancel
  • Pricing page

Common Issues

API client out of sync

Bash
1
task frontend:generate-client

Module not found

Bash
1
2
3
cd frontend
rm -rf node_modules
npm install

Build fails

Bash
1
2
3
4
5
6
# Check TypeScript errors
cd frontend
npm run type-check

# Fix errors, then
npm run build

Vite port conflict

Default port 5173 already in use:

Bash
1
2
3
4
# Kill process
lsof -ti:5173 | xargs kill -9

# Or change port in vite.config.ts