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

# Extension Configuration

> Configure and manage EverShop extensions for modular functionality

# Extension Configuration

Extensions are the core building blocks of EverShop's modular architecture. They encapsulate business logic, API endpoints, page components, and background jobs.

## Configuration Location

Extensions are configured in the `system.extensions` array within your configuration files:

* `config/default.json` - Base extension configuration
* `config/development.json` - Development overrides
* `config/production.json` - Production overrides

## Extension Schema

Each extension in the configuration array must follow this schema:

<ParamField path="name" type="string" required>
  Unique identifier for the extension. Used internally by EverShop to reference the extension.

  **Example**: `"offlinePayments"`, `"productCatalog"`
</ParamField>

<ParamField path="resolve" type="string" required>
  Path to the extension directory, relative to the project root.

  **Format**: `"extensions/{extension-name}"`

  **Example**: `"extensions/offlinePayments"`
</ParamField>

<ParamField path="enabled" type="boolean" required>
  Controls whether the extension is active. Set to `false` to disable without removing the configuration.

  **Default**: `true`
</ParamField>

## Configuration Example

Here's the actual extension configuration from `config/default.json`:

```json theme={null}
{
  "system": {
    "extensions": [
      {
        "name": "offlinePayments",
        "resolve": "extensions/offlinePayments",
        "enabled": true
      },
      {
        "name": "productCatalog",
        "resolve": "extensions/productCatalog",
        "enabled": true
      },
      {
        "name": "productReviews",
        "resolve": "extensions/productReviews",
        "enabled": true
      }
    ]
  }
}
```

## Built-in Extensions

This project includes the following extensions:

### offlinePayments

<Accordion title="Offline Payment Methods Extension">
  Provides offline payment methods for checkout, including:

  * Cash on Delivery (COD)
  * Bank Transfer

  **Location**: `extensions/offlinePayments/`

  **Components**:

  * `src/pages/frontStore/checkout/cod/CashOnDelivery.tsx`
  * `src/pages/frontStore/checkout/transfer/BankTransfer.tsx`

  **Package**:

  ```json theme={null}
  {
    "name": "offlinePayments",
    "version": "1.0.0",
    "private": true,
    "main": "src/index.ts"
  }
  ```
</Accordion>

### productCatalog

<Accordion title="Product Catalog Extension">
  Extends product functionality with additional catalog features.

  **Location**: `extensions/productCatalog/`

  **Components**:

  * GraphQL extensions for product types
  * Front store supplement information display

  **Files**:

  * `src/graphql/types/ProductExtension/ProductExtension.resolvers.js`
  * `src/pages/frontStore/productView/SupplementInfo.tsx`

  **Package**:

  ```json theme={null}
  {
    "name": "productCatalog",
    "version": "1.0.0",
    "private": true,
    "main": "src/index.ts"
  }
  ```
</Accordion>

### productReviews

<Accordion title="Product Reviews Extension">
  Enables customer reviews and ratings on product pages.

  **Location**: `extensions/productReviews/`

  **Components**:

  * Product review display on product detail pages

  **Files**:

  * `src/pages/frontStore/productView/ProductReviews.tsx`

  **Package**:

  ```json theme={null}
  {
    "name": "productReviews",
    "version": "1.0.0",
    "private": true,
    "main": "src/index.ts"
  }
  ```
</Accordion>

## Extension Directory Structure

A typical extension follows this structure:

```bash theme={null}
extensions/{extension-name}/
├── src/
│   ├── api/              # REST API endpoints
│   │   └── {endpoint}/
│   │       ├── route.json
│   │       └── [...middleware].ts
│   ├── pages/            # React page components
│   │   ├── frontStore/   # Customer-facing pages
│   │   └── admin/        # Admin panel pages
│   ├── graphql/          # GraphQL types and resolvers
│   │   └── types/
│   ├── subscribers/      # Event subscribers
│   ├── crons/            # Scheduled jobs
│   └── bootstrap.ts      # Extension initialization
├── dist/                 # Compiled output (auto-generated)
├── package.json
└── tsconfig.json
```

## Managing Extensions

### Enabling an Extension

To enable an existing extension:

1. Update `config/default.json`:
   ```json theme={null}
   {
     "system": {
       "extensions": [
         {
           "name": "myExtension",
           "resolve": "extensions/myExtension",
           "enabled": true
         }
       ]
     }
   }
   ```

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

<Warning>
  Enabling or disabling extensions requires a full rebuild with `npm run build`.
</Warning>

### Disabling an Extension

To temporarily disable an extension without removing it:

1. Set `enabled` to `false`:
   ```json theme={null}
   {
     "name": "productReviews",
     "resolve": "extensions/productReviews",
     "enabled": false
   }
   ```

2. Rebuild:
   ```bash theme={null}
   npm run build
   ```

<Note>
  Disabled extensions remain in the codebase but their routes, components, and logic are not loaded.
</Note>

### Adding a New Extension

To add a custom extension:

1. Create the extension directory:
   ```bash theme={null}
   mkdir -p extensions/myExtension/src
   ```

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

3. Create `tsconfig.json`:
   ```json theme={null}
   {
     "compilerOptions": {
       "module": "NodeNext",
       "target": "ES2018",
       "esModuleInterop": true,
       "skipLibCheck": true,
       "declaration": true,
       "outDir": "./dist",
       "rootDir": "./src"
     },
     "include": ["src"]
   }
   ```

4. Register in `config/default.json`:
   ```json theme={null}
   {
     "system": {
       "extensions": [
         {
           "name": "myExtension",
           "resolve": "extensions/myExtension",
           "enabled": true
         }
       ]
     }
   }
   ```

5. Rebuild:
   ```bash theme={null}
   npm run build
   ```

## Extension Development

### Bootstrap File

Extensions can include a `bootstrap.ts` file for initialization logic:

```typescript theme={null}
import path from 'path';
import { registerJob } from '@evershop/evershop/lib/cronjob';

export default function () {
  registerJob({
    name: 'myJob',
    schedule: '*/1 * * * *', // Every minute
    resolve: path.resolve(import.meta.dirname, 'crons', 'myJob.js'),
    enabled: true
  });
}
```

### API Endpoints

Create REST API endpoints with a `route.json` configuration:

```json theme={null}
{
  "methods": ["GET", "POST"],
  "path": "/api/my-endpoint",
  "access": "public"
}
```

### Page Components

Page components are React components with special exports:

```typescript theme={null}
// src/pages/frontStore/myPage/MyComponent.tsx
export default function MyComponent({ props }) {
  return <div>My Component</div>;
}

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

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

## Environment-Specific Configuration

You can enable different extensions per environment:

<Accordion title="Development Extensions">
  ```json theme={null}
  // config/development.json
  {
    "system": {
      "extensions": [
        {
          "name": "debugTools",
          "resolve": "extensions/debugTools",
          "enabled": true
        }
      ]
    }
  }
  ```
</Accordion>

<Accordion title="Production Extensions">
  ```json theme={null}
  // config/production.json
  {
    "system": {
      "extensions": [
        {
          "name": "debugTools",
          "resolve": "extensions/debugTools",
          "enabled": false
        },
        {
          "name": "analytics",
          "resolve": "extensions/analytics",
          "enabled": true
        }
      ]
    }
  }
  ```
</Accordion>

## Best Practices

### Extension Naming

* Use descriptive, lowercase names
* Use camelCase for multi-word names
* Prefix custom extensions to avoid conflicts (e.g., `mystore-shipping`)

### Extension Dependencies

* Keep extensions independent when possible
* Document any dependencies on other extensions
* Use event subscribers for inter-extension communication

### Version Control

* Commit extension source code to version control
* Exclude `dist/` directories (auto-generated)
* Document extension configuration in README files

## Common Issues

<Accordion title="Extension not loading after enabling">
  Ensure:

  1. The extension path in `resolve` is correct
  2. `package.json` exists in the extension directory
  3. You've run `npm run build` after configuration changes
  4. No syntax errors in extension code
</Accordion>

<Accordion title="TypeScript compilation errors">
  Verify:

  1. `tsconfig.json` is properly configured
  2. All dependencies are installed
  3. TypeScript types are available (`@types/react`, etc.)
  4. Import paths are correct
</Accordion>

## Related Configuration

* [Shop Settings](/api/config/shop-settings) - Configure language and currency
* [Theme Configuration](/api/config/themes) - Configure active theme

## Next Steps

* Learn about [Theme Configuration](/api/config/themes)
* Explore the sample extension structure
* Create your first custom extension