Introduction

Learn about EverShop, a modular Node.js e-commerce framework built with Express, PostgreSQL, and React

What is EverShop?

EverShop is a modern, modular e-commerce framework built on a powerful technology stack designed for flexibility and scalability. It follows a plugin-based architecture that separates business logic from presentation, making it easy to customize and extend your online store.

This project is built on EverShop version 2.1.1 with TypeScript support for both backend and frontend development.

Technology Stack

EverShop is built on proven, enterprise-grade technologies:

Backend

• Node.js - Runtime environment
• Express - Web framework
• PostgreSQL - Database
• GraphQL - API layer

Frontend

• React - UI components
• TypeScript - Type safety
• Tailwind CSS - Styling
• Server-side rendering - Performance

Architecture Overview

EverShop’s architecture is based on two fundamental pillars:

1. Extensions (Business Logic)

Extensions encapsulate all custom functionality in isolated, reusable modules:

extensions/[name]/
├── src/
│   ├── api/              // REST API endpoints
│   ├── pages/            // Page components
│   ├── subscribers/      // Event handlers
│   ├── crons/            // Scheduled jobs
│   ├── graphql/          // GraphQL types & resolvers
│   └── bootstrap.ts      // Extension initialization
├── package.json
└── tsconfig.json

2. Themes (Visual Presentation)

Themes define the visual appearance and user experience:

themes/[name]/
├── src/
│   └── pages/            // React components
│       ├── all/          // Global components
│       ├── homepage/     // Homepage components
│       └── account/      // Account pages
├── package.json
└── tsconfig.json

Key Features

Modular Architecture

Build features as independent extensions that can be enabled, disabled, or replaced without affecting the core system.

TypeScript First

Full TypeScript support with strict type checking for both backend logic and React components.

GraphQL API

Flexible GraphQL layer for efficient data fetching with type extensions and custom resolvers.

Hot Reload Development

Fast development workflow with hot module replacement for both backend and frontend code.

Component-Based UI

React components with area-based layouts, allowing precise control over component placement and rendering order.

Event-Driven

Powerful subscriber system for handling events and creating loosely coupled integrations.

Project Configuration

The current project is configured with:

• Language: Spanish (es)
• Currency: USD
• Active Extensions:
  • offlinePayments - Cash on delivery and bank transfer payment methods
  • productCatalog - Extended product information for supplements
  • productReviews - Customer review system
• Active Theme: anasuplements - Optimized for supplement e-commerce

Configuration System

EverShop uses a hierarchical configuration system:

config/
├── default.json          # Base configuration
├── development.json      # Development overrides
└── production.json       # Production overrides

Configuration is merged in this priority order:

1. .env - Environment variables (secrets, database credentials)
2. config/default.json - Base configuration
3. config/[environment].json - Environment-specific overrides

Example: Extension Registration

{
  "system": {
    "extensions": [
      {
        "name": "productCatalog",
        "resolve": "extensions/productCatalog",
        "enabled": true
      }
    ],
    "theme": "anasuplements"
  },
  "shop": {
    "language": "es",
    "currency": "USD"
  }
}

Data Flow

Understand how requests flow through the system:

1. Request Routing

   Express router matches the incoming request to the appropriate handler based on route.json configuration.

2. Middleware Processing

   Request passes through middleware chain (authentication, validation, body parsing).

3. GraphQL Data Fetching

   Page components execute GraphQL queries to fetch required data from the database.

4. Component Rendering

   React components render with fetched data, respecting area layout and sort order.

5. Event Broadcasting

   Subscribers listen for events and trigger background processing or integrations.

Core Principles

Never Modify Core Files

Never edit files in .evershop/ or node_modules/. All customizations must be encapsulated in extensions or themes.

Extension-Based Development

All custom features should be built as extensions:

• ✅ Create new extensions in extensions/[name]/
• ✅ Register extensions in config/default.json
• ✅ Use TypeScript for type safety
• ❌ Never modify core EverShop files
• ❌ Never put business logic in themes

Separation of Concerns

• Extensions = Business logic, APIs, data processing
• Themes = Visual presentation, styling, user experience

Next Steps

Quick Start

Get EverShop running locally in minutes

Installation Guide

Detailed installation and configuration instructions

Development

Learn how to build extensions and customize your store

API Reference

Complete API documentation and examples