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.

Themes in EverShop are built with React and TypeScript, and use Tailwind CSS for styling.

Theme Architecture

Directory Structure

Each theme follows a standardized structure:

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:

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

Use sortOrder to control the exact position within an area. Lower numbers render first.

Activating a Theme

Themes are activated in config/default.json:

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

   themes/mytheme/src/pages/homepage/Banner.tsx
   

2. Export the component with layout configuration:

   export default function Banner() {
     return <div className="banner">...</div>;
   }
   
   export const layout = {
     areaId: 'content',
     sortOrder: 5
   };
   

3. Build the theme:

   npm run build
   

Hot Reload

During development, use:

npm run dev

Changes to theme files will automatically rebuild and refresh.

Styling with Tailwind CSS

EverShop themes use Tailwind CSS utility classes:

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:

<div className="bg-[#2D5A3D] text-white">
  Branded content
</div>

Best Practice

Extract commonly used colors into CSS variables or Tailwind config for consistency across your theme.

TypeScript Configuration

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

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

Type Safety

Define props interfaces for your components:

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:

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

A complete EverShop store requires both a theme (for UI) and extensions (for functionality).

Next Steps

Ana's Supplements Theme

Explore a complete theme implementation

Styling Guide

Learn advanced styling techniques

Extensions Overview

Understand how extensions work

GraphQL Queries

Master data fetching in components