Nextjs project guidelines

These are my preffered project guidelines in nextjs:

Project Structure

/
├── public/
├── src/
│   ├── app/
│   ├── components/
│   ├── hooks/
│   ├── lib/
│   ├── styles/
│   ├── types/
│   └── views/
├── tests/
├── biome.json
├── next.config.js
├── package.json
├── tsconfig.json
└── README.md

- public/: For static assets
- src/app/: For Next.js 13+ app router pages and layouts
- src/components/: For reusable React components
- src/hooks/: For custom hooks, organized by area
- src/lib/: For utility functions and shared logic
- src/styles/: For global styles (if needed)
- src/types/: For TypeScript type definitions
- src/views/: For complex, page-specific components
- tests/: For test files

File Naming Conventions

- Use kebab-case for component files: user-profile.tsx
- Use camelCase for utility functions and files: formatDate.ts
- Use kebab-case for CSS modules (if used): button-styles.module.css
- For pages in the app/ directory, use the Next.js file conventions:
- page.tsx for the main page component
- layout.tsx for layout components
- loading.tsx for loading states
- error.tsx for error boundaries

TypeScript Guidelines

- Use interfaces, types, or classes as appropriate, but be consistent throughout the project
- Never use any type. Always specify a type, either locally or globally if used in multiple places. If any must be used, provide a detailed comment justifying its use.
- Use strict mode in tsconfig.json
- Use type inference when possible, but explicitly type function parameters and return types
- Use enum for a fixed set of values
- Use union types for variables that can be one of several types
- Use generics for reusable components and functions

React and Next.js Best Practices

- Use React Hook Form with Zod for all forms, utilizing shadcn components and setup where available
- Implement comprehensive testing, including Playwright for end-to-end tests and other appropriate testing methods
- Use functional components with hooks
- Implement proper error boundaries
- Use Next.js Image component for optimized images
- Implement proper SEO practices using Next.js head component or metadata API
- Use server-side rendering (SSR) or static site generation (SSG) when appropriate
- Use Tailwind CSS for styling whenever possible
- Use shadcn as the component library
- Create custom hooks for all forms, even if not reusable
- Use useMemo and useCallback for advanced logic functions to optimize performance

Code Style and Formatting

- Use Biome for code linting and formatting
- Configure Biome to automatically sort imports correctly
- Consider using Husky for pre-commit hooks to ensure code quality

API Calls and Data Fetching

- Use Next.js API routes for backend functionality (primarily for NextAuth and proxy endpoints)
- Use the main .NET API for most other backend functionality
- Document reasons for using Next.js API routes in special cases

Testing

- Implement comprehensive testing in the frontend
- Use Playwright for end-to-end testing
- Explore and implement other appropriate testing methods

Documentation

- Use JSDoc comments for functions and components
- Maintain a comprehensive README.md file
- Consider using Storybook for component documentation

Performance

- Implement code splitting using Next.js dynamic imports
- Use Next.js Image component for image optimization
- Implement proper caching strategies
- Use useMemo and useCallback for expensive computations and callback functions

Forms

- Use React Hook Form with Zod for all forms
- Utilize shadcn components and setup for forms where available
- If shadcn components don't exist, use community-created components or create custom ones based on shadcn
- Consider using subfolders for form hooks (e.g., `src/hooks/forms/matches/` for match-related form hooks)