> ## 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 Configuration

> Configure and customize EverShop themes for your store

# Theme Configuration

Themes control the visual presentation and user interface of your EverShop store. Unlike extensions which handle business logic, themes focus purely on the frontend experience.

## Configuration Location

The active theme is configured in the `system.theme` property:

* `config/default.json` - Base theme configuration
* `config/development.json` - Development theme override
* `config/production.json` - Production theme override

## Theme Configuration Schema

<ParamField path="system.theme" type="string" required>
  The name of the active theme directory. This should match a directory name in the `themes/` folder.

  **Example**: `"anasuplements"`, `"default"`, `"custom"`
</ParamField>

## Configuration Example

Here's the actual theme configuration from your EverShop project:

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

This configuration is consistent across all environments:

<Accordion title="config/default.json">
  ```json theme={null}
  {
    "shop": {
      "language": "es",
      "currency": "USD"
    },
    "system": {
      "extensions": [
        {
          "name": "offlinePayments",
          "resolve": "extensions/offlinePayments",
          "enabled": true
        },
        {
          "name": "productCatalog",
          "resolve": "extensions/productCatalog",
          "enabled": true
        },
        {
          "name": "productReviews",
          "resolve": "extensions/productReviews",
          "enabled": true
        }
      ],
      "theme": "anasuplements"
    }
  }
  ```
</Accordion>

<Accordion title="config/development.json">
  ```json theme={null}
  {
    "shop": {
      "language": "es",
      "currency": "USD"
    },
    "system": {
      "theme": "anasuplements"
    }
  }
  ```
</Accordion>

<Accordion title="config/production.json">
  ```json theme={null}
  {
    "shop": {
      "language": "es",
      "currency": "USD"
    },
    "system": {
      "theme": "anasuplements"
    }
  }
  ```
</Accordion>

## Active Theme: anasuplements

The current project uses the `anasuplements` theme, which is designed for a supplements e-commerce store.

### Theme Structure

```bash theme={null}
themes/anasuplements/
├── src/
│   └── pages/           # React page components
│       ├── account/     # Customer account pages
│       │   ├── Dashboard.tsx
│       │   ├── Login.tsx
│       │   └── Register.tsx
│       ├── all/         # Global components
│       │   ├── Footer.tsx
│       │   └── Header.tsx
│       └── homepage/    # Homepage components
│           ├── FeaturedProducts.tsx
│           ├── Features.tsx
│           └── Hero.tsx
├── dist/                # Compiled output (auto-generated)
├── package.json
└── tsconfig.json
```

### Theme Package Configuration

```json theme={null}
{
  "name": "anasuplements",
  "version": "1.0.0",
  "private": true,
  "main": "src/index.ts",
  "scripts": {
    "build": "evershop build:theme"
  },
  "devDependencies": {
    "@types/react": "^19.0.0"
  }
}
```

### Theme Components

The anasuplements theme includes:

#### Account Pages

* `Dashboard.tsx` - Customer account dashboard
* `Login.tsx` - Customer login page
* `Register.tsx` - Customer registration page

#### Global Components

* `Header.tsx` - Site-wide header navigation
* `Footer.tsx` - Site-wide footer

#### Homepage Components

* `Hero.tsx` - Hero section with main banner
* `FeaturedProducts.tsx` - Featured product carousel/grid
* `Features.tsx` - Store features/benefits section

### TypeScript Configuration

```json theme={null}
{
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ES2018",
    "lib": ["dom", "dom.iterable", "esnext"],
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "declaration": true,
    "sourceMap": true,
    "allowJs": true,
    "checkJs": false,
    "jsx": "react",
    "outDir": "./dist",
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "allowArbitraryExtensions": true,
    "strictNullChecks": true,
    "isolatedModules": false,
    "baseUrl": ".",
    "rootDir": "./src"
  },
  "include": ["src"]
}
```

## Theme Development

### Creating Page Components

Theme components are React components with special exports for layout configuration:

```typescript theme={null}
// themes/anasuplements/src/pages/homepage/Hero.tsx
import React from 'react';

export default function Hero() {
  return (
    <section className="hero">
      <h1>Welcome to Ana Supplements</h1>
    </section>
  );
}

// Layout configuration
export const layout = {
  areaId: 'content',
  sortOrder: 10
};

// Optional: GraphQL query for data fetching
export const query = `
  query {
    products(limit: 6) {
      id
      name
      price
    }
  }
`;
```

### Component Areas

EverShop uses a flexible area system for component placement:

| Area ID   | Description             |
| --------- | ----------------------- |
| `header`  | Header section          |
| `content` | Main content area       |
| `footer`  | Footer section          |
| `sidebar` | Sidebar (if applicable) |

### Sort Order

The `sortOrder` determines component rendering order within an area:

* Lower numbers render first
* Typical range: 10-100
* Step by 10s to allow insertion

```typescript theme={null}
export const layout = {
  areaId: 'content',
  sortOrder: 20  // Renders after components with sortOrder < 20
};
```

## Changing Themes

### Switch to a Different Theme

To change your active theme:

1. Update `config/default.json`:
   ```json theme={null}
   {
     "system": {
       "theme": "newThemeName"
     }
   }
   ```

2. Ensure the theme directory exists:
   ```bash theme={null}
   ls -la themes/newThemeName/
   ```

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

<Warning>
  Changing themes requires a full rebuild. Always test thoroughly after switching themes.
</Warning>

### Development vs Production Themes

You can use different themes per environment:

```json theme={null}
// config/development.json
{
  "system": {
    "theme": "development-theme"
  }
}

// config/production.json
{
  "system": {
    "theme": "anasuplements"
  }
}
```

## Creating a Custom Theme

### Step 1: Create Theme Directory

```bash theme={null}
mkdir -p themes/myCustomTheme/src/pages
```

### Step 2: Create package.json

```json theme={null}
{
  "name": "myCustomTheme",
  "version": "1.0.0",
  "private": true,
  "main": "src/index.ts",
  "scripts": {
    "build": "evershop build:theme"
  },
  "devDependencies": {
    "@types/react": "^19.0.0"
  }
}
```

### Step 3: Create tsconfig.json

```json theme={null}
{
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ES2018",
    "lib": ["dom", "dom.iterable", "esnext"],
    "jsx": "react",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src"]
}
```

### Step 4: Create Components

Create your first component:

```typescript theme={null}
// themes/myCustomTheme/src/pages/all/Header.tsx
import React from 'react';

export default function Header() {
  return (
    <header>
      <nav>My Custom Navigation</nav>
    </header>
  );
}

export const layout = {
  areaId: 'header',
  sortOrder: 10
};
```

### Step 5: Configure and Build

```json theme={null}
// config/default.json
{
  "system": {
    "theme": "myCustomTheme"
  }
}
```

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

## Styling and Assets

### CSS/Tailwind Integration

EverShop themes typically use Tailwind CSS for styling:

```typescript theme={null}
export default function Hero() {
  return (
    <section className="bg-gradient-to-r from-green-50 to-green-100 py-20">
      <div className="container mx-auto px-4">
        <h1 className="text-4xl font-bold text-green-800">
          Welcome to Our Store
        </h1>
      </div>
    </section>
  );
}
```

<Note>
  The anasuplements theme uses a green/mint color scheme:

  * Primary: `#2D5A3D` (Green)
  * Background: `#F8FAF9` (Pearl White)
  * Borders: `#E8F5E9` (Light Green)
</Note>

### Static Assets

Place static assets in the `public/` directory at the project root:

```bash theme={null}
public/
├── images/
├── fonts/
└── icons/
```

Reference in components:

```typescript theme={null}
<img src="/images/logo.png" alt="Logo" />
```

## Theme Organization

### Page Component Structure

Organize components by their purpose:

```bash theme={null}
themes/{theme-name}/src/pages/
├── all/              # Components used across all pages
│   ├── Header.tsx
│   ├── Footer.tsx
│   └── Layout.tsx
├── homepage/         # Homepage-specific components
│   ├── Hero.tsx
│   ├── Features.tsx
│   └── FeaturedProducts.tsx
├── account/          # Customer account pages
│   ├── Login.tsx
│   ├── Register.tsx
│   └── Dashboard.tsx
├── catalog/          # Product catalog pages
│   ├── ProductList.tsx
│   └── ProductView.tsx
└── checkout/         # Checkout pages
    ├── Cart.tsx
    └── Checkout.tsx
```

### Component Naming Conventions

* Use PascalCase for component files: `FeaturedProducts.tsx`
* Match directory names to page areas: `frontStore`, `admin`
* Use descriptive names that indicate purpose: `Hero.tsx`, `ProductGrid.tsx`

## Best Practices

### Theme Development

1. **Component Isolation**: Keep components focused on presentation
2. **Reusability**: Create shared components in the `all/` directory
3. **TypeScript**: Use TypeScript for type safety
4. **Responsive Design**: Design mobile-first with Tailwind utilities

### Version Control

* Commit theme source code (`src/`)
* Exclude compiled output (`dist/`)
* Document theme features in a README

### Testing

```bash theme={null}
# Development mode with hot-reload
npm run dev

# Production build testing
npm run build && npm run start
```

## Common Issues

<Accordion title="Theme not loading after configuration">
  Verify:

  1. Theme name in config matches directory name exactly
  2. `package.json` exists in theme directory
  3. You've run `npm run build` after configuration changes
  4. No TypeScript compilation errors
</Accordion>

<Accordion title="Components not rendering">
  Check:

  1. Component exports default function
  2. `layout` export is properly configured
  3. `areaId` matches available areas
  4. No runtime errors in browser console
</Accordion>

<Accordion title="Styles not applying">
  Ensure:

  1. Tailwind classes are correctly spelled
  2. Custom CSS is properly imported
  3. Build process completed successfully
  4. Browser cache is cleared
</Accordion>

## Related Configuration

* [Shop Settings](/api/config/shop-settings) - Configure language and currency
* [Extension Configuration](/api/config/extensions) - Configure enabled extensions

## Next Steps

* Explore the anasuplements theme source code
* Customize theme components for your brand
* Learn about Tailwind CSS integration
* Create reusable component libraries