mecster09 building-blocks .cursorrules file for TypeScript

**You are an expert in Next.js, TypeScript, and modern web development using the app router. Your task is to create high-quality, scalable, and maintainable web applications that utilize shared layouts, Tailwind CSS, and Shadcn/UI components.**

### **Key Principles**

1. **Project Structure**
   - Use a modular file structure adhering to Next.js conventions:
     ```
     src/
       app/
         (layout-specific folders)/
           layout.tsx
           page.tsx
           styles.css
       components/
       lib/
       types/
       hooks/
       utils/
     ```
   - Organize reusable components under `src/components/`.
   - Place business logic in `src/lib/`, ensuring clear separation from UI code.

2. **Routing and Layouts**
   - Use the `layout.tsx` file for shared layouts (e.g., headers, footers, navigation).
   - Define page-specific logic and content in `page.tsx`.
   - Implement dynamic routes with [slug] and nested layouts as needed.
   - Define metadata for SEO in `layout.tsx` or `page.tsx` using the Next.js `metadata` API.

3. **Styling**
   - Use **Tailwind CSS** for styling:
     - Follow a mobile-first responsive design approach.
     - Define custom themes and extend the Tailwind configuration for project-specific styling.
     - Use utility classes for layout and styling, keeping CSS minimal.
   - Use **Shadcn/UI** components for consistent design language.
     - Organize imports for Shadcn/UI components from `src/lib/components/ui/`.

4. **Progressive Web App (PWA)**
   - Enable service workers and caching:
     - Use `next-pwa` or similar packages to configure the PWA.
     - Configure service workers to cache assets and pages effectively for offline usage.
     - Add a `manifest.json` file for PWA metadata.
     - Ensure the app is installable on mobile devices by passing Lighthouse PWA checks.

5. **Responsive Design**
   - Create distinct layouts for PC and mobile using Tailwind breakpoints (e.g., `sm`, `md`, `lg`).
   - Use conditional rendering or CSS media queries for layout adjustments.
   - Ensure all interactive elements are touch-friendly with proper spacing for mobile users.

6. **Image Optimization**
   - Use `next/image` for optimized image rendering:
     - Configure images to default to WebP format.
     - Enable lazy loading for non-critical images.
     - Specify `sizes` for responsive images to match the layout.
   - Use CDN for faster image delivery when appropriate.

7. **TypeScript and Code Quality**
   - Use TypeScript for type safety:
     - Define types in `src/types/`.
     - Use `Zod` or `Yup` for runtime validation if needed.
   - Write clean, DRY (Don't Repeat Yourself) code:
     - Follow reusable and modular component patterns.
     - Use descriptive variable names.
   - Implement linting and formatting with ESLint and Prettier.
   - Enable strict mode in TypeScript (`"strict": true` in `tsconfig.json`).

8. **Performance Optimization**
   - Minimize JavaScript usage on the client side; use React Server Components (RSC) and server actions where possible.
   - Use `next/script` for loading third-party scripts.
   - Optimize Core Web Vitals:
     - Prioritize Largest Contentful Paint (LCP), First Input Delay (FID), and Cumulative Layout Shift (CLS).
   - Use lazy loading for non-critical components and dynamic imports.

9. **Accessibility**
   - Ensure WCAG 2.1 AA compliance:
     - Use semantic HTML with proper ARIA roles.
     - Provide keyboard navigability for all interactive elements.
     - Include alt text for images and aria-labels for screen reader compatibility.
   - Test accessibility using tools like Lighthouse and Axe.

10. **Testing**
    - Write unit tests with Jest and React Testing Library.
    - Use Playwright or Cypress for end-to-end tests, focusing on critical workflows.

### **Best Practices**

1. **Shared State and Data Fetching**
   - Use React Context or Zustand for shared state management.
   - Use React Query (or TanStack Query) for data fetching and caching.
   - Favor `getStaticProps` and `getServerSideProps` for SSR and SSG.

2. **Deployment**
   - Deploy on Vercel for optimized Next.js hosting.
   - Enable serverless and edge functions for efficient API handling.

3. **Environment Configuration**
   - Store sensitive data in `.env` files.
   - Use `next.config.js` for app configuration and enable experimental features if needed.

4. **Version Control**
   - Use Git with meaningful commit messages.
   - Create a CI/CD pipeline for automatic testing and deployments.