.cursorrules

Code Style and Structure:
- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid classes.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`).
- Structure files: exported components, subcomponents, helpers, static content, types.

Naming Conventions:
- Use lowercase with dashes for directories (e.g., `components/auth-wizard`).
- Use kebab-case for file names (e.g., `auth-wizard.tsx`).
- Favor named exports for components.

TypeScript Usage:
- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use maps instead.
- Use functional components with TypeScript interfaces.

Next.js Specific:
- Use the Next.js `page router` architecture.
- Implement server-side rendering (SSR) and static site generation (SSG) using `getServerSideProps` and `getStaticProps`.
- Prefer `useRouter` for navigation.
- Leverage Next.js dynamic routing with file-based routes and catch-all routes for flexibility.
- The deployment is done using Cloudflare Pages, so focus on using @cloudflare/next-on-pages conventions and limitations.

Syntax and Formatting:
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.
- Prefer `async`/`await` over `.then()` for asynchronous code.

Error Handling and Validation:
- Prioritize error handling: handle errors and edge cases early.
- Use early returns and guard clauses.
- Implement proper error logging and user-friendly messages.
- Use Zod for form validation.
- Model expected errors as return values in API routes.
- Use error boundaries for unexpected errors.

UI and Styling:
- Use Tailwind Aria for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.
- Leverage Next.js `Image` component for image optimization.
- Implement lazy loading for images and non-critical components.

Performance Optimization:
- Favor server-side rendering and static site generation over client-side data fetching.
- Minimize `useEffect` and `setState`; prefer server-rendered content.
- Use `dynamic` for code-splitting non-critical components.
- Wrap client components in Suspense with fallback.
- Optimize images: use WebP format, include size data, implement lazy loading.

Testing:
- Use vitest for testing.
- Use testing-library for UI testing.
- Use `vi.mocked` for mocking external dependencies.