> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Antony-Figueroa/my-evershop-app/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme System Overview

> Understanding EverShop's theme architecture and customization capabilities

## What are Themes?

In EverShop, themes control the visual presentation and user interface of your store. Themes are separate from business logic (which lives in extensions) and contain only page components and styling.

<Note>
  Themes in EverShop are built with **React** and **TypeScript**, and use **Tailwind CSS** for styling.
</Note>

## Theme Architecture

### Directory Structure

Each theme follows a standardized structure:

```bash theme={null}
themes/[theme-name]/
├── src/
│   └── pages/           # Page components
│       ├── all/         # Components for all pages (Header, Footer)
│       ├── homepage/    # Homepage-specific components
│       ├── account/     # Account pages (Login, Register, Dashboard)
│       └── ...
├── dist/                # Compiled output (auto-generated)
├── package.json         # Theme metadata
└── tsconfig.json        # TypeScript configuration
```

### Page Component Structure

Theme components are organized by **area** and **page type**:

* **`all/`** - Components that appear on every page (Header, Footer, Navigation)
* **`homepage/`** - Homepage-specific sections (Hero, Features, Featured Products)
* **`account/`** - Account management pages (Login, Register, Dashboard)
* **`catalog/`** - Product listing and detail pages
* **`checkout/`** - Checkout flow components

## Component Exports

Every page component in a theme must export specific values:

```typescript theme={null}
// Default export: The React component
export default function MyComponent() {
  return <div>Content</div>;
}

// Layout configuration: Where and when to render
export const layout = {
  areaId: 'content',    // Where to render (header, content, footer)
  sortOrder: 10          // Rendering priority (lower = first)
};

// Optional: GraphQL query for data fetching
export const query = `
  query {
    products {
      id
      name
    }
  }
`;
```

### Area IDs

Components are placed in different areas of the page:

* **`header`** - Top of every page
* **`content`** - Main content area
* **`footer`** - Bottom of every page
* **`sidebar`** - Side navigation or filters

<Tip>
  Use `sortOrder` to control the exact position within an area. Lower numbers render first.
</Tip>

## Activating a Theme

Themes are activated in `config/default.json`:

```json theme={null}
{
  "system": {
    "theme": "anasuplements"
  }
}
```

The theme name must match the directory name in `themes/`.

## Development Workflow

### Creating Components

1. Create a new `.tsx` file in the appropriate area directory:
   ```bash theme={null}
   themes/mytheme/src/pages/homepage/Banner.tsx
   ```

2. Export the component with layout configuration:
   ```typescript theme={null}
   export default function Banner() {
     return <div className="banner">...</div>;
   }

   export const layout = {
     areaId: 'content',
     sortOrder: 5
   };
   ```

3. Build the theme:
   ```bash theme={null}
   npm run build
   ```

### Hot Reload

During development, use:

```bash theme={null}
npm run dev
```

Changes to theme files will automatically rebuild and refresh.

## Styling with Tailwind CSS

EverShop themes use Tailwind CSS utility classes:

```tsx theme={null}
export default function Button() {
  return (
    <button className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
      Click Me
    </button>
  );
}
```

### Custom Colors

Define brand colors directly in your components:

```tsx theme={null}
<div className="bg-[#2D5A3D] text-white">
  Branded content
</div>
```

<Card title="Best Practice" icon="lightbulb">
  Extract commonly used colors into CSS variables or Tailwind config for consistency across your theme.
</Card>

## TypeScript Configuration

Themes use TypeScript with React support. The `tsconfig.json` includes:

```json theme={null}
{
  "compilerOptions": {
    "jsx": "react",
    "target": "ES2018",
    "module": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strictNullChecks": true
  }
}
```

### Type Safety

Define props interfaces for your components:

```typescript theme={null}
type HeaderProps = {
  storeName?: string;
  categories?: {
    name: string;
    url: string;
  }[];
};

export default function Header({ storeName, categories }: HeaderProps) {
  // ...
}
```

## Data Fetching with GraphQL

Components can fetch data using GraphQL queries:

```typescript theme={null}
export const query = `
  query {
    customer {
      firstName
      lastName
      email
    }
    orders(limit: 5) {
      orderId
      total
      status
    }
  }
`;

export default function Dashboard({ customer, orders }) {
  // Data is automatically passed as props
  return <div>Welcome, {customer.firstName}</div>;
}
```

## Theme vs Extensions

| Aspect     | Themes                        | Extensions                             |
| ---------- | ----------------------------- | -------------------------------------- |
| Purpose    | Visual presentation           | Business logic                         |
| Contains   | React components, styles      | API routes, subscribers, GraphQL types |
| Location   | `themes/`                     | `extensions/`                          |
| Technology | React, TypeScript, Tailwind   | Node.js, Express, PostgreSQL           |
| Examples   | Header, Footer, Product Cards | Payment processing, order management   |

<Note>
  A complete EverShop store requires **both** a theme (for UI) and extensions (for functionality).
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Ana's Supplements Theme" icon="palette" href="/themes/anasuplements">
    Explore a complete theme implementation
  </Card>

  <Card title="Styling Guide" icon="paintbrush" href="/themes/anasuplements">
    Learn advanced styling techniques
  </Card>

  <Card title="Extensions Overview" icon="plug" href="/extensions/overview">
    Understand how extensions work
  </Card>

  <Card title="GraphQL Queries" icon="database" href="/api/graphql/queries">
    Master data fetching in components
  </Card>
</CardGroup>