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:

name

string

required

Unique identifier for the extension. Used internally by EverShop to reference the extension.Example: "offlinePayments", "productCatalog"

resolve

string

required

Path to the extension directory, relative to the project root.Format: "extensions/{extension-name}"Example: "extensions/offlinePayments"

enabled

boolean

required

Controls whether the extension is active. Set to false to disable without removing the configuration.Default: true

Configuration Example

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

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

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:

{
  "name": "offlinePayments",
  "version": "1.0.0",
  "private": true,
  "main": "src/index.ts"
}

productCatalog

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:

{
  "name": "productCatalog",
  "version": "1.0.0",
  "private": true,
  "main": "src/index.ts"
}

productReviews

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:

{
  "name": "productReviews",
  "version": "1.0.0",
  "private": true,
  "main": "src/index.ts"
}

Extension Directory Structure

A typical extension follows this structure:

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:

Update config/default.json:

{
  "system": {
    "extensions": [
      {
        "name": "myExtension",
        "resolve": "extensions/myExtension",
        "enabled": true
      }
    ]
  }
}

Rebuild the application:
```
npm run build
```

Enabling or disabling extensions requires a full rebuild with npm run build.

Disabling an Extension

To temporarily disable an extension without removing it:

Set enabled to false:

{
  "name": "productReviews",
  "resolve": "extensions/productReviews",
  "enabled": false
}

Rebuild:
```
npm run build
```

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

Adding a New Extension

To add a custom extension:

Create the extension directory:
```
mkdir -p extensions/myExtension/src
```

Create package.json:

{
  "name": "myExtension",
  "version": "1.0.0",
  "private": true,
  "main": "src/index.ts",
  "scripts": {
    "build": "tsc"
  },
  "devDependencies": {
    "@types/react": "^19.0.0"
  }
}

Create tsconfig.json:

{
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ES2018",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src"]
}

{
  "system": {
    "extensions": [
      {
        "name": "myExtension",
        "resolve": "extensions/myExtension",
        "enabled": true
      }
    ]
  }
}

Rebuild:
```
npm run build
```

Extension Development

Bootstrap File

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

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:

{
  "methods": ["GET", "POST"],
  "path": "/api/my-endpoint",
  "access": "public"
}

Page Components

Page components are React components with special exports:

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

Development Extensions

// config/development.json
{
  "system": {
    "extensions": [
      {
        "name": "debugTools",
        "resolve": "extensions/debugTools",
        "enabled": true
      }
    ]
  }
}

Production Extensions

// config/production.json
{
  "system": {
    "extensions": [
      {
        "name": "debugTools",
        "resolve": "extensions/debugTools",
        "enabled": false
      },
      {
        "name": "analytics",
        "resolve": "extensions/analytics",
        "enabled": true
      }
    ]
  }
}

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

Extension not loading after enabling

Ensure:

The extension path in resolve is correct
package.json exists in the extension directory
You’ve run npm run build after configuration changes
No syntax errors in extension code

TypeScript compilation errors

Verify:

tsconfig.json is properly configured
All dependencies are installed
TypeScript types are available (@types/react, etc.)
Import paths are correct

Shop Settings - Configure language and currency
Theme Configuration - Configure active theme

Next Steps

Learn about Theme Configuration
Explore the sample extension structure
Create your first custom extension

GraphQL API

REST API

Configuration

Extension Configuration

Extension Configuration

Configuration Location

Extension Schema

Configuration Example

Built-in Extensions

offlinePayments

productCatalog

productReviews

Extension Directory Structure

Managing Extensions

Enabling an Extension

Disabling an Extension

Adding a New Extension

Extension Development

Bootstrap File

API Endpoints

Page Components

Environment-Specific Configuration

Best Practices

Extension Naming

Extension Dependencies

Version Control

Common Issues

Next Steps

Build docs developers (and LLMs) love

GraphQL API

REST API

Configuration

Documentation Index

​Extension Configuration

​Configuration Location

​Extension Schema

​Configuration Example

​Built-in Extensions

​offlinePayments

​productCatalog

​productReviews

​Extension Directory Structure

​Managing Extensions

​Enabling an Extension

​Disabling an Extension

​Adding a New Extension

​Extension Development

​Bootstrap File

​API Endpoints

​Page Components

​Environment-Specific Configuration

​Best Practices

​Extension Naming

​Extension Dependencies

​Version Control

​Common Issues

​Related Configuration

​Next Steps

Build docs developers (and LLMs) love

Extension Configuration

Configuration Location

Extension Schema

Configuration Example

Built-in Extensions

offlinePayments

productCatalog

productReviews

Extension Directory Structure

Managing Extensions

Enabling an Extension

Disabling an Extension

Adding a New Extension

Extension Development

Bootstrap File

API Endpoints

Page Components

Environment-Specific Configuration

Best Practices

Extension Naming

Extension Dependencies

Version Control

Common Issues

Related Configuration

Next Steps