Cursor rule

1---
2alwaysApply: true
3---
4 
5# Frontend Development Workflow
6 
7## Architecture
8 
9This project uses Next.js with Firebase integration and Material-UI components. The architecture follows a component-based pattern with clear separation of concerns between presentation, business logic, and data management.
10 
11## Primary Rules
12 
13Below are the rules that you must follow when developing frontend functionality:
14 
15### Template and Components
16 
17- Use Material-UI components as the foundation
18- Explore MUI documentation for ready-to-use components before creating custom ones
19- Mix components from different MUI versions if necessary (with caution)
20- Keep unused template components during early development stages
21- Make components reusable but maintainable and understandable
22 
23### Theme and Context
24 
25- Customize application through theme context (`ThemeProvider`)
26- Use separate contexts for different themes if needed (app theme, widget theme)
27- Place theme contexts at the appropriate level (top-level for app, specific for widgets)
28- Disable CssBaseline for widget themes to avoid style conflicts
29- Always use theme variables for styling (colors, spacing, typography)
30- Add custom colors in theme configuration (e.g., `theme.palette.customColors.primaryDark`)
31 
32### User Experience (UX)
33 
34- **Always** adopt the perspective of a critical user
35- Use `LoadingScreen` or skeletons for loading states
36- Display `EmptyContent` component for empty tables/lists
37- Use `LoadingButton` for form actions (`loading={isSubmitting}`)
38- Show informative error messages using snackbar notifications
39- Ensure the app is self-explanatory - users should never wonder "what's happening?"
40- Test on various mobile devices and large screens
41- Use `100dvh` instead of `100vh` for mobile compatibility
42 
43### Code Quality
44 
45- Balance code quality with development speed
46- Add comments where logic is complex
47- Use TypeScript strictly - avoid 'any' type
48- Keep functions and components focused (single responsibility)
49- Use proper error boundaries and error handling
50 
51### State Management
52 
53- Use React Context for global state (avoid Redux unless necessary)
54- Leverage Firebase real-time listeners for live data
55- Use local state for component-specific data
56- Implement optimistic UI updates where appropriate
57 
58### Performance Optimization
59 
60- Use `useCallback` and `useMemo` efficiently
61- Pay attention to dependency arrays in hooks
62- Lazy load components when appropriate
63- Implement proper code splitting
64 
65### Authorization
66 
67- Use auth context with `onAuthStateChanged`
68- Use `AuthGuard` for protected content
69- Always show loading indicators during auth processes
70- Handle auth errors gracefully
71 
72## Workflow
73 
74When building new features, follow this systematic workflow:
75 
76### 0. Planning Phase
77 
78Before starting, create a comprehensive to-do list following this exact process:
79 
80- Understand the feature requirements
81- Identify affected components and pages
82- List all necessary UI components
83- Plan the data flow and state management
84- Consider edge cases and error states
85 
86### 1. Design Analysis
87 
88- Review existing components that can be reused
89- Identify new components that need to be created
90- Plan responsive behavior for all screen sizes
91 
92### 2. Component Development
93 
94```tsx
95// Start with the component structure
96// components/features/NewFeature.tsx
97import { useState, useEffect } from "react";
98import { Box, Paper, Typography, Skeleton } from "@mui/material";
99import { useAuth } from "@/auth/useAuth";
100import { useSnackbar } from "notistack";
101 
102export function NewFeature() {
103  const [loading, setLoading] = useState(true);
104  const [data, setData] = useState(null);
105  const { user } = useAuth();
106  const { enqueueSnackbar } = useSnackbar();
107 
108  // Always handle loading states
109  if (loading) {
110    return <Skeleton variant="rectangular" height={200} />;
111  }
112 
113  // Always handle empty states
114  if (!data) {
115    return <EmptyContent title="No data available" />;
116  }
117 
118  return <Paper sx={{ p: 3 }}>{/* Component content */}</Paper>;
119}
120```
121 
122### 3. Firebase Integration
123 
124```tsx
125// lib/firestore.ts - Define operations
126export const dataOperations = {
127  async create(data: DataType) {
128    try {
129      const docRef = await addDoc(collections.data, data);
130      return docRef.id;
131    } catch (error) {
132      console.error("Error creating document:", error);
133      throw error;
134    }
135  },
136 
137  async getById(id: string) {
138    const docRef = doc(collections.data, id);
139    const docSnap = await getDoc(docRef);
140    return docSnap.exists() ? docSnap.data() : null;
141  },
142};
143 
144// hooks/useData.ts - Create real-time hook
145export function useData(dataId: string) {
146  const [data, setData] = useState(null);
147  const [loading, setLoading] = useState(true);
148 
149  useEffect(() => {
150    const unsubscribe = onSnapshot(
151      doc(db, "data", dataId),
152      (doc) => {
153        setData(doc.exists() ? doc.data() : null);
154        setLoading(false);
155      },
156      (error) => {
157        console.error("Error fetching data:", error);
158        setLoading(false);
159      }
160    );
161 
162    return unsubscribe;
163  }, [dataId]);
164 
165  return { data, loading };
166}
167```
168 
169### 4. Form Handling
170 
171```tsx
172// Always use controlled components with proper validation
173import { useForm, Controller } from "react-hook-form";
174import { yupResolver } from "@hookform/resolvers/yup";
175import * as yup from "yup";
176 
177const schema = yup.object({
178  name: yup.string().required("Name is required"),
179  email: yup.string().email("Invalid email").required("Email is required"),
180});
181 
182export function DataForm() {
183  const {
184    control,
185    handleSubmit,
186    formState: { errors, isSubmitting },
187  } = useForm({
188    resolver: yupResolver(schema),
189  });
190  const { enqueueSnackbar } = useSnackbar();
191 
192  const onSubmit = async (data) => {
193    try {
194      await dataOperations.create(data);
195      enqueueSnackbar("Data saved successfully", { variant: "success" });
196    } catch (error) {
197      enqueueSnackbar(error.message, { variant: "error" });
198    }
199  };
200 
201  return (
202    <form onSubmit={handleSubmit(onSubmit)}>
203      <Controller
204        name="name"
205        control={control}
206        render={({ field }) => (
207          <TextField
208            {...field}
209            label="Name"
210            error={!!errors.name}
211            helperText={errors.name?.message}
212            fullWidth
213            margin="normal"
214          />
215        )}
216      />
217 
218      <LoadingButton
219        type="submit"
220        variant="contained"
221        loading={isSubmitting}
222        fullWidth
223      >
224        Submit
225      </LoadingButton>
226    </form>
227  );
228}
229```
230 
231### 5. Testing
232 
233- Check if front end compiles and runs.
234-
235 
236## Common Patterns
237 
238### Notification Pattern
239 
240```tsx
241const { enqueueSnackbar } = useSnackbar();
242 
243// Success
244enqueueSnackbar("Operation successful", { variant: "success" });
245 
246// Error
247enqueueSnackbar("Something went wrong", { variant: "error" });
248 
249// Info
250enqueueSnackbar("Please note...", { variant: "info" });
251```
252 
253### Protected Route Pattern
254 
255```tsx
256// Use AuthGuard wrapper
257<AuthGuard>
258  <ProtectedContent />
259</AuthGuard>;
260 
261// Or conditional rendering
262const { isAuthenticated } = useAuth();
263if (!isAuthenticated) {
264  return <Navigate to="/signin" />;
265}
266```
267 
268## Navigation Rules
269 
270### Next.js Link
271 
272```tsx
273// Correct - use href
274<Link href="/dashboard">
275  <Button>Go to Dashboard</Button>
276</Link>
277```
278 
279### MUI Link with Navigation
280 
281```tsx
282// Correct - use router.push
283import { useRouter } from "next/navigation";
284 
285const router = useRouter();
286<MuiLink component="button" onClick={() => router.push("/dashboard")}>
287  Dashboard
288</MuiLink>;
289```
290 
291## Debugging Checklist
292 
293When something doesn't work:
294 
2951. Check browser console for errors
2962. Verify Firebase configuration
2973. Check network tab for API calls
2984. Verify authentication state
2995. Check component props and state
3006. Verify data types match interfaces
3017. Check for race conditions
3028. Verify cleanup functions in useEffect
303