cro-metrics-code the-store .cursorrules file for TypeScript

# Project Instructions

Use the project specification and guidelines as you build the app.

Write the complete code for every step. Do not get lazy.

Your goal is to completely finish whatever I ask for.

## Overview

This is a e-commerce store that uses commerce-kit from Your Next Store.

commerce-kit is a simple TypeScript library designed specifically for e-commerce applications built with Next.js.

It provides a range of utilities to interact with products, categories, and orders, seamlessly integrating with Stripe for payment processing.

## Tech Stack

- Frontend: Next.js, Tailwindcss, Shadcn/UI, Stripe, commerce-kit,
- Backend: Server Actions, Stripe, Vercel
- Deployment: Vercel

## Project Structure

### General Structure

- `actions` - Server actions
  - `cart-actions.ts` - Cart related actions
- `app` - Next.js app router
  - `(store)` - Store route group
    - `(.)cart-overlay` - A parallel route for the cart overlay
    - `[...segments]` - Catch all dynamic route for the store
      - `page.tsx` - Page for the route
    - `@modal` - A parallel route for modals
      - `[...segments]` - Catch all dynamic route for the store
        - `page.tsx` - Page for the route
    - `cart` - Cart route
      - `layout.tsx` - Layout for the route
      - `page.tsx` - Page for the route
    - ...other routes
    - `layout.tsx` - Layout for the route group
    - `page.tsx` - Page for the route group
  - `api` - API routes
    - `route` - An example route
      - `_components` - One-off components for the route
    - `layout.tsx` - Layout for the route
    - `page.tsx` - Page for the route
  - `global-error.tsx` - Global error page
  - `global.css` - Global styles
  - `layout.tsx` - Root layout
  - `not-found.tsx` - Not found page
  - `page.tsx` - Root page
  - `robots.ts` - Generates robots.txt
  - `sitemap.ts` - Generates sitemap.xml
- `context` - Context providers
- `hooks` - Custom hooks
- `images` - Image assets
- `lib` - Library code and utils
- `public` - Static assets
- `ui` - UI components

## Rules

Follow these rules when building the project.

### General Rules

- Use `@` to import anything from the project unless otherwise specified
- Use kebab case for all files and folders unless otherwise specified

#### Env Rules

- If you update environment variables, update the `.env.example` file
- All environment variables should go in `.env`
- Do not expose environment variables to the frontend
- Use `NEXT_PUBLIC_` prefix for environment variables that need to be accessed from the frontend
- @t3-oss/env-nextjs is used to add type safety and validation to environment variables and is located in `src/env/server.ts` (for server-side) and `src/env/client.ts` (for client-side)
- After environmental variables have been added to `.env` and the appropriate `src/env/client.ts` or `src/env/server.ts` file, you may import environment variables as follows:
  - `import { env } from '@/env/server';` for server components and server actions
  - `import { env } from '@/env/client';` for client components

#### Type Rules

Follow these rules when working with types.

- When importing types, use `@/types`
- Name files like `example-types.ts`
- All types should go in `types`
- Make sure to export the types in `types/index.ts`
- Prefer interfaces over type aliases

An example of a type:

`types/actions-types.ts`

```ts
export type ActionState<T> =
  | { isSuccess: true; message: string; data: T }
  | { isSuccess: false; message: string; data?: never };
```

And exporting it:

`types/index.ts`

```ts
export * from './actions-types';
```

### Frontend Rules

Follow these rules when working on the frontend.

It uses Next.js, Tailwindcss, Shadcn/UI, Stripe, commerce-kit

#### General Rules

- Use `lucide-react` for icons

#### Components

- Use divs instead of other html tags unless otherwise specified
- Use actions, not queries, in the app
- Always tag a component with either `use server` or `use client` at the top, including layouts and pages

##### Organization

- All components be named using kebab case like `example-component.tsx` unless otherwise specified
- Put components in a `/_components` folder in the route if one-off components for that route
- Put components in a `/components` folder from the root if shared components

##### Data Fetching

- Fetch data in server components and pass the data down as props to client components.
- Use server actions from `/actions` to mutate data.

##### Server Components

- Use `"use server"` at the top of the file.
- Implement Suspense for asynchronous data fetching to show loading states while data is being fetched.
- If no asynchronous logic is required for a given server component, you do not need to wrap the component in `<Suspense>`. You can simply return the final UI directly since there is no async boundary needed.
- If asynchronous fetching is required, you can use a `<Suspense>` boundary and a fallback to indicate a loading state while data is loading.

Example of a server layout:

```tsx
'use server';

export default async function ExampleServerLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return children;
}
```

Example of a server page (with async logic):

```tsx
'use server';

import { Suspense } from 'react';
import { SomeAction } from '@/actions/some-actions';
import SomeComponent from './_components/some-component';
import SomeSkeleton from './_components/some-skeleton';

export default async function ExampleServerPage() {
  return (
    <Suspense fallback={<SomeSkeleton className="some-class" />}>
      <SomeComponentFetcher />
    </Suspense>
  );
}

async function SomeComponentFetcher() {
  const { data } = await SomeAction();
  return <SomeComponent className="some-class" initialData={data || []} />;
}
```

Example of a server page (no async logic required):

```tsx
'use server';

import SomeClientComponent from './_components/some-client-component';

// In this case, no asynchronous work is being done, so no Suspense or fallback is required.
export default async function ExampleServerPage() {
  return <SomeClientComponent initialData={[]} />;
}
```

Example of a server component:

```tsx
'use server';

interface ExampleServerComponentProps {
  // Your props here
}

export async function ExampleServerComponent({
  props,
}: ExampleServerComponentProps) {
  // Your code here
}
```

##### Client Components

- Use `"use client"` at the top of the file
- Client components can safely rely on props passed down from server components, or handle UI interactions without needing `<Suspense>` if there’s no async logic.

Example of a client page:

```tsx
'use client';

export default function ExampleClientPage() {
  // Your code here
}
```

Example of a client component:

```tsx
'use client';

interface ExampleClientComponentProps {
  initialData: any[];
}

export default function ExampleClientComponent({
  initialData,
}: ExampleClientComponentProps) {
  // Client-side logic here
  return <div>{initialData.length} items</div>;
}
```