Yaltopia-Ticket-Admin/dev-docs/QUICK_REFERENCE.md

Quick Reference Guide

Common Commands

# Development
npm run dev                 # Start dev server (http://localhost:5173)
npm run build              # Build for production
npm run build:prod         # Build with production env
npm run preview            # Preview production build
npm run lint               # Run ESLint
npm run lint:fix           # Fix ESLint errors
npm run type-check         # TypeScript type checking

# Deployment
vercel --prod              # Deploy to Vercel
netlify deploy --prod      # Deploy to Netlify
docker build -t app .      # Build Docker image
docker run -p 80:80 app    # Run Docker container

Environment Variables

# Required
VITE_API_URL=http://localhost:3000/api/v1

# Optional
VITE_ENV=development
VITE_ANALYTICS_ID=
VITE_SENTRY_DSN=

File Structure

├── src/
│   ├── app/              # App config (query client)
│   ├── components/       # Reusable components
│   │   └── ui/          # UI components
│   ├── layouts/          # Layout components
│   ├── lib/              # Utils & API client
│   ├── pages/            # Page components
│   │   └── admin/       # Admin pages
│   ├── App.tsx          # Main app
│   └── main.tsx         # Entry point
├── .env.example          # Env template
├── vite.config.ts        # Vite config
├── package.json          # Dependencies
└── README.md            # Documentation

Key Files

File	Purpose
src/lib/api-client.ts	API configuration & helpers
src/app/query-client.ts	React Query setup
src/components/ErrorBoundary.tsx	Error handling
vite.config.ts	Build configuration
.env.example	Environment template

API Client Usage

import { adminApiHelpers } from '@/lib/api-client';

// Get users
const response = await adminApiHelpers.getUsers({ page: 1, limit: 20 });

// Get user by ID
const user = await adminApiHelpers.getUser(userId);

// Update user
await adminApiHelpers.updateUser(userId, { isActive: false });

// Delete user
await adminApiHelpers.deleteUser(userId);

React Query Usage

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

// Fetch data
const { data, isLoading, error } = useQuery({
  queryKey: ['users', page],
  queryFn: async () => {
    const response = await adminApiHelpers.getUsers({ page });
    return response.data;
  },
});

// Mutate data
const mutation = useMutation({
  mutationFn: async (data) => {
    await adminApiHelpers.updateUser(id, data);
  },
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['users'] });
  },
});

Routing

import { useNavigate, useParams } from 'react-router-dom';

// Navigate
const navigate = useNavigate();
navigate('/admin/users');

// Get params
const { id } = useParams();

Toast Notifications

import { toast } from 'sonner';

toast.success('Success message');
toast.error('Error message');
toast.info('Info message');
toast.warning('Warning message');

Deployment Quick Start

Vercel

npm i -g vercel
vercel login
vercel --prod

Netlify

npm i -g netlify-cli
netlify login
netlify deploy --prod

Docker

docker build -t yaltopia-admin .
docker run -p 80:80 yaltopia-admin

Troubleshooting

Build fails

rm -rf node_modules package-lock.json
npm install
npm run build

Type errors

npm run type-check

Blank page after deploy

• Check browser console
• Verify API URL in env vars
• Check server config for SPA routing

API calls failing

• Check CORS on backend
• Verify API URL
• Check network tab in DevTools

Security Checklist

• HTTPS enabled
• Environment variables set
• CORS configured
• Security headers added
• Error tracking set up
• Monitoring configured

Performance Tips

• Use code splitting for large routes
• Lazy load heavy components
• Optimize images
• Enable compression (gzip/brotli)
• Use CDN for static assets

Useful Links

• React Query Docs
• React Router Docs
• Vite Docs
• Tailwind CSS Docs
• Radix UI Docs

Support

• Check README.md for detailed docs
• See DEPLOYMENT.md for deployment guide
• Review SECURITY.md for security best practices
• Read PRODUCTION_READY_SUMMARY.md for status