squirrelogic squirrel-template .cursorrules file for TypeScript

You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI, Supabase, Tailwind, and Vercel AI SDK.

**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 component, subcomponents, helpers, static content, types.
- All html forms should be created as separate components and placed in the components/forms directory.
- All html form components should use react-hook-form.
- All html forms will submit to a next-safe-action using the useAction hook.
- All html forms will use shadcn Form components instead of normal html components.
- All html forms should toast on success or failure.
- All html forms should use the SubmitButton for the submit button.
- All forms will submit to a server action located in the actions folder.
- All server actions will have a schema defined for their input using Zod.
- All server actions will be created using next-safe-action.
- All server actions will use the fluent style starting with a safe action client that are defined in actions/safe-action.ts [authActionClient for private actions, actionClientWithMeta for public actions].
- You will use dot notation to call [safe action client].schema([schema]).action([async action function])
- The action functions take in an object with the parsedInput property holding the input data.

**Naming Conventions**

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.

**TypeScript Usage**

- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use const objects or as const assertions instead.
- Use functional components with TypeScript interfaces.

**Syntax and Formatting**

- Use arrow functions for components and handlers.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.

**UI and Styling**

- Use Shadcn UI, Radix, and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.

**Performance Optimization**

- Minimize 'use client', 'useEffect', and 'useState'; favor React Server Components (RSC).
- Wrap client components in Suspense with fallback.
- Use dynamic loading for non-critical components.
- Optimize images: use Next.js Image component, include size data, implement lazy loading.

**Database Querying & Data Model Creation**

- Use Supabase SDK for data fetching and querying.
- For data model creation, use Supabase's schema builder.

**Key Conventions**

- Use 'nuqs' for URL search parameter state management.
- Optimize Web Vitals (LCP, CLS, FID).
- Limit 'use client':
- Favor server components and Next.js SSR.
- Use only for Web API access in small components.
- Avoid for data fetching or state management.

**Vercel AI SDK Integration**

- Use Vercel AI SDK for building AI-powered features.
- Implement AI SDK Core for generating text, structured objects, and tool calls with LLMs.
- Utilize AI SDK UI hooks for building chat interfaces.
- Leverage AI SDK RSC for streaming generative user interfaces with React Server Components.

**Data Fetching and API Routes**

- Use Next.js App Router conventions for data fetching and API routes.
- Implement efficient caching and revalidation strategies using Next.js built-in features.
- Use route handlers (route.ts) for API routes in the App Router.

**Error Handling and Loading States**

- Implement error boundaries and error.tsx files for error handling.
- Use loading.tsx files for managing loading states.

**SEO and Metadata**

- Use Next.js 15's metadata API for SEO optimization.

**Project Structure**

- This is a turbo monorepo.
  apps <!-- Applications (websites) -->
  |-- api <!-- Supabase project -->
  |-- functions <!-- Edge Functions -->
  |-- migrations <!-- Sql Migrations -->
  |-- app <!-- Main Application -->
  |-- actions <!-- Server Actions -->
  |-- safe-action.ts <!-- safe action clients (actionClientWithMeta for public paths, authActionClient for private paths) -->
  |-- app <!-- Website source code -->
  |-- components <!-- Application components -->
  |-- hooks <!-- React Hooks -->
  |-- messages <!-- Internationalization language files -->
  |-- docs
  |-- web
  packages <!-- Shared Packages -->
  |-- analytics <!-- Analytics Library -->
  |-- email <!-- Email Templates Library -->
  |-- jobs <!-- Jobs Library uses Trigger.dev -->
  |-- kv <!-- KV Library uses upstash redis -->
  |-- logger <!-- Pino logger -->
  |-- supabase <!-- Supabase library -->
  |-- clients <!-- Supabase Client Wrappers -->
  |-- client.ts <!-- Browser Client -->
  |-- middleware.ts <!-- Next.JS SSR Middleware -->
  |-- server.ts <!-- Server Client -->
  |-- mutations <!-- Mutation functions, each area should be a separate file and re-exported in the index.ts (e.g. auth.ts, gdpr-settings.ts, organization.ts) -->
  |-- queries <!-- Query functions, each area should be a separate file and re-exported in the index.ts -->
  |-- types <!-- Library types -->
  |-- ui <!-- UI Component Library uses shadcn -->

- All pages should exist under the [locale] folder.
- Forms should post to server actions in the actions folder
- All forms should use react-hook-form
- Make sure to use next-intl for internationalization.
- Translations belong in the messages/[locale].json files
- When adding translations, start with the english version in en.json. Then add the same translation keys in the other languages but with their respective translation.
- Server actions
  - each area should have 1 schema file for all area schemas.
  - each area should have 1 file per server action.
  - All server actions are next-safe-actions.

**Follow Next.js docs for Data Fetching, Rendering, and Routing.**