Creating Extensions

Learn how to create custom extensions in EverShop

Extensions are the primary way to add custom functionality to your EverShop store. They allow you to encapsulate features like API endpoints, event subscribers, cron jobs, and GraphQL types without modifying the core codebase.

What is an Extension?

An extension is a modular package that can contain:

• API Endpoints - RESTful routes for custom operations
• Event Subscribers - React to system events
• Cron Jobs - Scheduled background tasks
• GraphQL Types - Custom data types and resolvers
• Page Components - Server-side rendered React components
• Middleware - Custom request processing logic

Directory Structure

A typical extension follows this structure:

extensions/[extension-name]/
├── src/
│   ├── api/              # REST API endpoints
│   ├── subscribers/      # Event subscribers
│   ├── crons/           # Scheduled jobs
│   ├── graphql/         # GraphQL types & resolvers
│   ├── pages/           # Page components
│   └── bootstrap.ts     # Extension initialization
├── dist/                # Compiled output (auto-generated)
├── package.json
└── tsconfig.json

Creating Your First Extension

Bootstrap File

The bootstrap.ts file is the entry point for your extension. It’s executed when the application starts and is ideal for registering cron jobs, initializing services, or performing setup tasks.

Example: Registering a Cron Job

Here’s a real example from the sample extension:

src/bootstrap.ts

import path from 'path';
import { registerJob } from '@evershop/evershop/lib/cronjob';

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

The bootstrap.ts file is optional. Only create it if you need to perform initialization tasks.

Extension Configuration

Enabling/Disabling Extensions

To enable or disable an extension, modify config/default.json:

{
  "system": {
    "extensions": [
      {
        "name": "sample",
        "resolve": "extensions/sample",
        "enabled": true  // Set to false to disable
      }
    ]
  }
}

Environment-Specific Configuration

You can override settings in environment-specific config files:

config/development.json

{
  "system": {
    "extensions": [
      {
        "name": "sample",
        "enabled": true
      }
    ]
  }
}

{
  "system": {
    "extensions": [
      {
        "name": "sample",
        "enabled": false
      }
    ]
  }
}

Real-World Example: Sample Extension

The EverShop repository includes a complete sample extension that demonstrates all extension features:

extensions/sample/
├── src/
│   ├── api/
│   │   └── createFoo/
│   │       ├── route.json
│   │       ├── bodyParser.ts
│   │       └── [bodyParser]createFoo.ts
│   ├── subscribers/
│   │   └── product_created/
│   │       └── consoleLog.js
│   ├── crons/
│   │   └── everyMinute.ts
│   ├── graphql/
│   │   └── types/
│   │       └── Foo/
│   │           ├── Foo.graphql
│   │           └── Foo.resolvers.js
│   ├── pages/
│   │   └── frontStore/
│   │       └── homepage/
│   │           └── FooList.tsx
│   └── bootstrap.ts
├── package.json
└── tsconfig.json

Best Practices

Use TypeScript: Always use TypeScript (.ts/.tsx) for new code to benefit from type safety and better developer experience.

• Modular Organization - Keep related files together in feature-specific directories
• Naming Conventions - Use descriptive names that reflect the extension’s purpose
• Environment Variables - Store sensitive data in .env files, not in configuration
• Error Handling - Always implement proper error handling in API endpoints and subscribers
• Documentation - Include a Readme.md file explaining what your extension does

Common Patterns

Extension with API Only

extensions/payment-gateway/
├── src/
│   └── api/
│       ├── webhook/
│       └── process-payment/
└── package.json

Extension with Subscribers Only

extensions/email-notifications/
├── src/
│   └── subscribers/
│       ├── order_placed/
│       ├── order_shipped/
│       └── customer_registered/
└── package.json

Extension with GraphQL

extensions/custom-data/
├── src/
│   └── graphql/
│       └── types/
│           ├── CustomType/
│           └── AnotherType/
└── package.json

Troubleshooting

Extension Not Loading

1. Verify the extension is registered in config/default.json
2. Ensure enabled is set to true
3. Run npm run build to rebuild the application
4. Check for TypeScript compilation errors

Build Errors

1. Verify tsconfig.json is properly configured
2. Check that all imports are correct
3. Ensure dependencies are installed: npm install

Next Steps

API Endpoints

Learn how to create RESTful API endpoints

Event Subscribers

React to system events with subscribers

Cron Jobs

Schedule background tasks

Page Components

Build custom page components