ChiaXinLiang next15-shadcn-start .cursorrules file for TypeScript

# Rules Reference
This file serves as the main configuration file for Next.js 15 and React 19 projects. It references and implements the detailed rules located in the `rules/` directory. Each section corresponds to specific rule files in the rules folder that provide comprehensive implementation details.

# Framework Versions
- Next.js: 15.x
- React: 19.x (Release Candidate)

Provide guidance and best practices for a software development project according to specified rules and conventions for environment configuration, app router structure, component organization, API routes, styling, and other critical aspects. Ensure that all aspects of the project conform to the described standards and conventions.

# Steps
# Each step references corresponding YAML files in the rules/ directory and follows Next.js 15 conventions

1. **Environment Configuration** (rules/environment.yaml)
   - Validate environment variables using Zod for type safety.
   - Store sensitive data in `.env.local` and never commit `.env` files to version control.
   - Provide documentation for environment variables in `.env.example`.

2. **App Router Structure** (rules/app-router.yaml)
   - Use default exports for page components and React Server Components as default practices.
   - Implement the 'use client' directive as necessary.
   - Use standardized file naming conventions such as `page.tsx` and `layout.tsx`.

3. **Component Organization** (rules/components.yaml)
   - Categorize components into directories: `components/common/`, `components/ui/`, and `components/[feature]/`.
   - Use PascalCase for component names and limit files to one component each.
   - Define TypeScript interfaces for props to enforce type safety.

4. **Shadcn Components** (rules/components.yaml)
   - Utilize destructured imports to maintain readability and include accessibility features.
   - Use the `cn()` utility for merging `className` attributes.
   - Adhere to default styling patterns provided by the framework.

5. **API Routes** (rules/api.yaml)
   - Export HTTP method handlers, validate requests using Zod, and ensure comprehensive error handling.
   - Utilize 'force-static' caching when applicable to optimize performance.

6. **Styling** (rules/styling.yaml)
   - Apply Tailwind CSS for styling and adhere to shadcn's styling variables.
   - Restrict styles to the specific file of the component to maintain separation.

7. **TypeScript Types** (rules/types.yaml)
   - Centralize shared types and export through an `index.ts`.
   - Provide descriptive names and JSDoc comments for all types for clarity.

8. **State Management** (rules/state.yaml)
   - Leverage React Context for global state and zustand for complex state management solutions.
   - Follow immutability best practices to maintain state integrity.

9. **Utilities** (rules/utils.yaml)
   - Write utilities as pure functions and ensure testability.
   - Document utilities using TypeScript annotations.

10. **Server Actions** (rules/server-actions.yaml)
    - Use the 'use server' directive and validate data with Zod.
    - Implement CSRF protection and comprehensive error handling strategies.

11. **Database Management** (rules/database.yaml)
    - Employ Prisma for database interactions, ensuring effective schema management and migrations.
    - Follow proper normalization practices and use transactions for integrity.
    - Implement appropriate caching strategies.

12. **Authentication** (rules/auth.yaml)
    - Implement authentication using NextAuth.js, securing APIs effectively.
    - Manage sessions securely to prevent unauthorized access.

13. **Middleware and Caching** (rules/middleware.yaml, rules/caching.yaml)
    - Follow edge runtime constraints for middleware development.
    - Control caching explicitly using `fetchCache` and `Cache-Control` headers.

14. **Forms** (rules/forms.yaml)
    - Utilize next/form for form navigation and implement prefetching capabilities to enhance user experience.

# Framework-Specific Features
## Next.js 15
- Enhanced App Router with improved caching strategies
- Static and Dynamic Route Handlers
- Support for next.config.ts TypeScript configuration
- Enhanced Forms with next/form for client-side navigation
- Improved metadata API
- Static Route Indicator in development

## React 19
- Use React 19 Server Components by default
- Improved Suspense integration
- Enhanced streaming capabilities
- Support for use client/server directives
- Improved asset loading strategies
- Enhanced error boundary handling

# Output Format

Provide the final documentation or code files based on the specified sections. Ensure responses are structured as detailed instructions or formatted templates for each section, maintaining clarity and adherence to the established rules and naming conventions.

# Notes
- Pay careful attention to naming conventions and export practices.
- Ensure validation, error handling, and accessibility features are included as specified.
- Optimize implementations for security and performance.
- Refer to individual rule files in the rules/ directory for detailed implementation guidelines.

# Rule Files Reference
All implementation details, conventions, and best practices are defined in YAML files within the rules/ directory. See rules/main.yaml for the complete rule set organization.