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

system.theme

string

required

The name of the active theme directory. This should match a directory name in the themes/ folder.Example: "anasuplements", "default", "custom"

Configuration Example

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

{
  "system": {
    "theme": "anasuplements"
  }
}

This configuration is consistent across all environments:

config/default.json

{
  "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"
  }
}

config/development.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "theme": "anasuplements"
  }
}

config/production.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "theme": "anasuplements"
  }
}

Active Theme: anasuplements

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

Theme Structure

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

{
  "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

{
  "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:

// 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

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:

Update config/default.json:

{
  "system": {
    "theme": "newThemeName"
  }
}

Ensure the theme directory exists:
```
ls -la themes/newThemeName/
```
Rebuild the application:
```
npm run build
```

Changing themes requires a full rebuild. Always test thoroughly after switching themes.

Development vs Production Themes

You can use different themes per environment:

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

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

Creating a Custom Theme

Step 1: Create Theme Directory

mkdir -p themes/myCustomTheme/src/pages

Step 2: Create package.json

{
  "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

{
  "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:

// 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

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

npm run build

Styling and Assets

CSS/Tailwind Integration

EverShop themes typically use Tailwind CSS for styling:

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>
  );
}

The anasuplements theme uses a green/mint color scheme:

Primary: #2D5A3D (Green)
Background: #F8FAF9 (Pearl White)
Borders: #E8F5E9 (Light Green)

Static Assets

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

public/
├── images/
├── fonts/
└── icons/

Reference in components:

<img src="/images/logo.png" alt="Logo" />

Theme Organization

Page Component Structure

Organize components by their purpose:

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

Component Isolation: Keep components focused on presentation
Reusability: Create shared components in the all/ directory
TypeScript: Use TypeScript for type safety
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

# Development mode with hot-reload
npm run dev

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

Common Issues

Theme not loading after configuration

Verify:

Theme name in config matches directory name exactly
package.json exists in theme directory
You’ve run npm run build after configuration changes
No TypeScript compilation errors

Components not rendering

Check:

Component exports default function
layout export is properly configured
areaId matches available areas
No runtime errors in browser console

Styles not applying

Ensure:

Tailwind classes are correctly spelled
Custom CSS is properly imported
Build process completed successfully
Browser cache is cleared

Shop Settings - Configure language and currency
Extension Configuration - 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

​Theme Configuration

​Configuration Location

​Theme Configuration Schema

​Configuration Example

​Active Theme: anasuplements

​Theme Structure

​Theme Package Configuration

​Theme Components

​Account Pages

​Global Components

​Homepage Components

​TypeScript Configuration

​Theme Development

​Creating Page Components

​Component Areas

​Sort Order

​Changing Themes

​Switch to a Different Theme

​Development vs Production Themes

​Creating a Custom Theme

​Step 1: Create Theme Directory

​Step 2: Create package.json

​Step 3: Create tsconfig.json

​Step 4: Create Components

​Step 5: Configure and Build

​Styling and Assets

​CSS/Tailwind Integration

​Static Assets

​Theme Organization

​Page Component Structure

​Component Naming Conventions

​Best Practices

​Theme Development

​Version Control

​Testing

​Common Issues

​Related Configuration

​Next Steps

Theme Configuration

Configuration Location

Theme Configuration Schema

Configuration Example

Active Theme: anasuplements

Theme Structure

Theme Package Configuration

Theme Components

Account Pages

Global Components

Homepage Components

TypeScript Configuration

Theme Development

Creating Page Components

Component Areas

Sort Order

Changing Themes

Switch to a Different Theme

Development vs Production Themes

Creating a Custom Theme

Step 1: Create Theme Directory

Step 2: Create package.json

Step 3: Create tsconfig.json

Step 4: Create Components

Step 5: Configure and Build

Styling and Assets

CSS/Tailwind Integration

Static Assets

Theme Organization

Page Component Structure

Component Naming Conventions

Best Practices

Theme Development

Version Control

Testing

Common Issues

Related Configuration

Next Steps