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

# Project Structure

> Directory organization, file naming conventions, and structural patterns in EverShop

## Root Directory Layout

Here's the complete structure of an EverShop application:

```
my-evershop-app/
├── config/                    # Configuration files
│   ├── default.json          # Base configuration
│   ├── development.json      # Dev environment overrides
│   └── production.json       # Production environment overrides
├── extensions/                # Business logic modules
│   ├── offlinePayments/      # Payment extension
│   ├── productCatalog/       # Product management
│   ├── productReviews/       # Review system
│   └── sample/               # Example extension
├── themes/                    # Visual themes
│   └── anasuplements/        # Active theme
├── translations/              # Internationalization
│   └── es/                   # Spanish translations
├── public/                    # Static assets
│   └── favicon.ico
├── .evershop/                 # Build output (DO NOT EDIT)
├── node_modules/              # Dependencies (DO NOT EDIT)
├── package.json               # Project dependencies
└── .gitignore                 # Git exclusions
```

<Note>
  **Important**: Never modify files in `.evershop/` or `node_modules/`. These directories are auto-generated.
</Note>

## Extension Structure

Extensions contain all **business logic** for your application. Here's the detailed structure:

### Example: Sample Extension

```
extensions/sample/
├── src/
│   ├── api/                   # REST API endpoints
│   │   └── createFoo/
│   │       ├── route.json     # Route configuration
│   │       ├── bodyParser.ts  # Middleware
│   │       └── [bodyParser]createFoo.ts  # Main handler
│   ├── pages/                 # Page components
│   │   └── frontStore/
│   │       └── homepage/
│   │           └── FooList.tsx
│   ├── graphql/              # GraphQL definitions
│   │   └── types/
│   │       └── Foo/
│   │           └── Foo.graphql
│   ├── subscribers/          # Event handlers
│   │   └── product_created/
│   │       └── productCreatedHandler.ts
│   ├── crons/                # Scheduled jobs
│   │   └── everyMinute.ts
│   └── bootstrap.ts          # Extension initialization
├── dist/                     # Compiled output (auto-generated)
├── package.json              # Extension dependencies
├── tsconfig.json             # TypeScript config
└── Readme.md
```

<Accordion title="Extension Directory Breakdown">
  <ResponseField name="src/api/" type="directory">
    REST API endpoints with route configuration

    **Structure**: `api/[endpointName]/`

    * `route.json` - Defines HTTP methods, path, and access control
    * `[middleware]handler.ts` - Request handlers with middleware chain
  </ResponseField>

  <ResponseField name="src/pages/" type="directory">
    React page components for admin or frontStore

    **Structure**: `pages/[area]/[pageName]/ComponentName.tsx`

    * Exports default component, `layout`, and optionally `query`
  </ResponseField>

  <ResponseField name="src/graphql/" type="directory">
    GraphQL type definitions and resolvers

    **Structure**: `graphql/types/[TypeName]/`

    * `TypeName.graphql` - Schema definition
    * `TypeName.resolvers.js` - Query/mutation resolvers
  </ResponseField>

  <ResponseField name="src/subscribers/" type="directory">
    Event handlers that respond to system events

    **Structure**: `subscribers/[event_name]/handler.ts`
  </ResponseField>

  <ResponseField name="src/crons/" type="directory">
    Scheduled background jobs

    **Structure**: `crons/jobName.ts`

    * Registered in `bootstrap.ts`
  </ResponseField>

  <ResponseField name="bootstrap.ts" type="file">
    Extension initialization file that runs on startup

    * Register cron jobs
    * Set up database connections
    * Configure services
  </ResponseField>
</Accordion>

### Real Example: API Endpoint

Here's how the sample extension defines a REST API:

<CodeGroup>
  ```json extensions/sample/src/api/createFoo/route.json theme={null}
  {
    "methods": ["POST"],
    "path": "/foos",
    "access": "private"
  }
  ```

  ```typescript extensions/sample/src/api/createFoo/[bodyParser]createFoo.ts theme={null}
  import { EvershopRequest, EvershopResponse } from '@evershop/evershop';

  export default (request: EvershopRequest, response: EvershopResponse, next) => {
    const { name, description } = request.body;

    if (!name || !description) {
      return response
        .status(400)
        .json({ error: 'Name and description are required' });
    }

    const newFoo = {
      id: Date.now(),
      name,
      description
    };

    response.status(201).json({
      success: true,
      data: { foo: newFoo }
    });
  };
  ```
</CodeGroup>

<Note>
  The `[bodyParser]` prefix means this middleware runs **after** the `bodyParser` middleware in the chain.
</Note>

## Theme Structure

Themes handle **visual presentation only**. They should NOT contain business logic.

### Example: Anasuplements Theme

```
themes/anasuplements/
├── src/
│   └── pages/
│       ├── account/           # Account-related pages
│       │   ├── Dashboard.tsx
│       │   ├── Login.tsx
│       │   └── Register.tsx
│       ├── all/               # Components for all pages
│       │   ├── Header.tsx
│       │   └── Footer.tsx
│       └── homepage/          # Homepage-specific components
├── dist/                      # Compiled output (auto-generated)
├── package.json
└── tsconfig.json
```

<Accordion title="Theme Page Areas">
  <ResponseField name="pages/all/" type="directory">
    Components that appear on **every page**

    Examples:

    * Header navigation
    * Footer
    * Cookie consent banners
  </ResponseField>

  <ResponseField name="pages/account/" type="directory">
    Components for **account-related pages**

    Examples:

    * Login forms
    * Registration
    * Dashboard
  </ResponseField>

  <ResponseField name="pages/homepage/" type="directory">
    Components for the **homepage only**

    Examples:

    * Hero sections
    * Featured products
    * Promotional banners
  </ResponseField>
</Accordion>

### Real Example: Header Component

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

type HeaderProps = {
  storeName?: string;
  categories?: { name: string; url: string; }[];
};

export default function Header({ 
  storeName = "Ana's Suplements", 
  categories = [] 
}: HeaderProps) {
  return (
    <header className="bg-[#F8FAF9] border-b border-[#E8F5E9]">
      <div className="container mx-auto px-4 py-4">
        <div className="flex items-center justify-between">
          <a href="/" className="text-2xl font-bold text-[#2D5A3D]">
            {storeName}
          </a>
          
          <nav className="hidden md:flex space-x-6">
            {categories.map((category, index) => (
              <a 
                key={index} 
                href={category.url}
                className="text-[#4A5568] hover:text-[#2D5A3D] transition-colors"
              >
                {category.name}
              </a>
            ))}
          </nav>
        </div>
      </div>
    </header>
  );
}

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

<Note>
  The theme uses **custom colors** (`#2D5A3D` for primary green) defined in the design system.
</Note>

## File Naming Conventions

### API Endpoints

<CodeGroup>
  ```text Pattern theme={null}
  api/[endpointName]/[middlewareName]handler.ts
  ```

  ```text Example theme={null}
  api/createFoo/[bodyParser]createFoo.ts
  api/createFoo/[authenticate]authorize.ts
  ```
</CodeGroup>

**Rules**:

* Middleware prefix `[name]` determines execution order
* Alphabetical sorting: `[authenticate]` runs before `[bodyParser]`
* The final handler typically has the endpoint name

### Page Components

<CodeGroup>
  ```text Pattern theme={null}
  pages/[area]/[pageName]/ComponentName.tsx
  ```

  ```text Examples theme={null}
  pages/all/Header.tsx
  pages/frontStore/homepage/FooList.tsx
  pages/account/Dashboard.tsx
  ```
</CodeGroup>

**Rules**:

* Use PascalCase for component files
* Area determines where component renders: `all`, `frontStore`, `admin`, `account`
* Must export default function and `layout` object

### GraphQL Types

<CodeGroup>
  ```text Pattern theme={null}
  graphql/types/[TypeName]/[TypeName].graphql
  graphql/types/[TypeName]/[TypeName].resolvers.js
  ```

  ```text Example theme={null}
  graphql/types/Foo/Foo.graphql
  graphql/types/Foo/Foo.resolvers.js
  ```
</CodeGroup>

### Subscribers

<CodeGroup>
  ```text Pattern theme={null}
  subscribers/[event_name]/handler.ts
  ```

  ```text Examples theme={null}
  subscribers/product_created/notifyAdmin.ts
  subscribers/order_placed/sendConfirmation.ts
  ```
</CodeGroup>

### Cron Jobs

<CodeGroup>
  ```text Pattern theme={null}
  crons/jobName.ts
  ```

  ```text Examples theme={null}
  crons/everyMinute.ts
  crons/dailyReport.ts
  crons/cleanupOldOrders.ts
  ```
</CodeGroup>

## TypeScript Configuration

Both extensions and themes use TypeScript:

```json extensions/sample/tsconfig.json theme={null}
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

<Note>
  Extensions and themes are compiled separately during the build process.
</Note>

## Package Structure

### Root Package

```json package.json theme={null}
{
  "name": "my-evershop-app",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "scripts": {
    "setup": "evershop install",
    "start": "evershop start",
    "build": "evershop build",
    "dev": "evershop dev"
  },
  "dependencies": {
    "@evershop/evershop": "2.1.1"
  },
  "devDependencies": {
    "@types/express": "5.0.6",
    "@types/node": "25.3.3",
    "@types/react": "19.2.14",
    "typescript": "5.9.3"
  }
}
```

### Extension Package

```json extensions/sample/package.json theme={null}
{
  "name": "sample-evershop-extension",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "tsc": "tsc"
  }
}
```

### Theme Package

```json themes/anasuplements/package.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"
  }
}
```

## Static Assets

Place public files in the `public/` directory:

```
public/
├── favicon.ico
├── images/
│   ├── logo.png
│   └── banner.jpg
└── fonts/
    └── custom-font.woff2
```

<Note>
  Files in `public/` are served at the root URL. For example, `public/favicon.ico` is accessible at `/favicon.ico`.
</Note>

## Translations

Store internationalization files in `translations/`:

```
translations/
├── es/              # Spanish
│   ├── common.json
│   └── products.json
└── en/              # English
    ├── common.json
    └── products.json
```

## Build Output

During build, EverShop generates:

```
.evershop/               # Compiled application
├── build/              # Server-side code
└── public/             # Client-side bundles

extensions/*/dist/      # Compiled extensions
themes/*/dist/          # Compiled themes
```

<Warning>
  These directories are in `.gitignore` and should **never be committed** to version control.
</Warning>

## Working with Structure

<Steps>
  <Step title="Create Extension">
    ```bash theme={null}
    mkdir -p extensions/myExtension/src
    cd extensions/myExtension
    npm init -y
    ```
  </Step>

  <Step title="Register in Config">
    Add to `config/default.json`:

    ```json theme={null}
    {
      "system": {
        "extensions": [
          {
            "name": "myExtension",
            "resolve": "extensions/myExtension",
            "enabled": true
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Add TypeScript Config">
    Copy `tsconfig.json` from `extensions/sample/`
  </Step>

  <Step title="Build and Run">
    ```bash theme={null}
    npm run dev
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration System" icon="gear" href="/architecture/configuration">
    Learn how config files control extensions and themes
  </Card>

  <Card title="Create Extension" icon="puzzle-piece" href="/guides/creating-extensions">
    Build your first custom extension
  </Card>
</CardGroup>