Installation

System Requirements

Before installing EverShop, ensure your system meets these requirements:

Runtime

Node.js 18.0 or higher

node --version

Database

PostgreSQL 12.0 or higher

psql --version

Package Manager

npm 9.0 or higher

npm --version

Build Tools

TypeScript 5.9+ (included in devDependencies)

Installation Steps

Install Node.js

Download and install Node.js from nodejs.org or use a version manager:

nvm (Linux/macOS)
nvm-windows
Direct Download

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 18
nvm install 18
nvm use 18
nvm alias default 18

# Download from github.com/coreybutler/nvm-windows
# Then install Node.js
nvm install 18
nvm use 18

Install PostgreSQL

Ubuntu/Debian
macOS
Windows

# Update package list
sudo apt update

# Install PostgreSQL
sudo apt install postgresql postgresql-contrib

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Using Homebrew
brew install postgresql@14

# Start PostgreSQL
brew services start postgresql@14

Create Database

Create a new PostgreSQL database for your store:

# Switch to postgres user
sudo -u postgres psql

-- Create database
CREATE DATABASE evershop;

-- Create user (optional)
CREATE USER evershop_user WITH PASSWORD 'your_secure_password';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE evershop TO evershop_user;

-- Exit
\q

Clone or Create Project

If starting from scratch:

# Create project directory
mkdir my-evershop-app
cd my-evershop-app

# Initialize npm project
npm init -y

Or clone existing project:

git clone <your-repository-url>
cd my-evershop-app

Install Dependencies

Install all required packages:

npm install

This installs the dependencies from package.json:

{
  "dependencies": {
    "@evershop/evershop": "2.1.1"
  },
  "devDependencies": {
    "@parcel/watcher": "2.5.6",
    "@types/config": "3.3.5",
    "@types/express": "5.0.6",
    "@types/node": "25.3.3",
    "@types/pg": "8.18.0",
    "@types/react": "19.2.14",
    "execa": "9.6.1",
    "typescript": "5.9.3"
  }
}

Configure Environment

Create a .env file in the project root:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=evershop
DB_USER=evershop_user
DB_PASSWORD=your_secure_password

# Server Configuration
NODE_ENV=development
PORT=3000

# Session Secret (generate a random string)
SESSION_SECRET=your_random_session_secret_here

# Admin Credentials (for initial setup)
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123

Security: Never commit .env to version control. It’s already in .gitignore:

# .gitignore
.env
.env.local
.env.*.local

Run Initial Setup

Initialize the database and install EverShop:

npm run setup

This command (evershop install) will:

Create all database tables
Set up initial data and schemas
Configure default settings
Create admin user
Initialize extensions

Start Development Server

Launch the application:

npm run dev

The server will start at http://localhost:3000

Development mode includes:

Hot module replacement
Source maps for debugging
Verbose error messages
Auto-compilation of TypeScript

Configuration Files

Package Configuration

Your package.json defines the project structure:

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

npm run setup

Runs evershop install to initialize the database and system. Use this once during initial installation.

npm run dev

Runs evershop dev to start the development server with hot reload. Use this during development.

npm run build

Runs evershop build to compile TypeScript and bundle assets for production.

npm run start

Runs evershop start to start the production server. Run build first.

Store Configuration

The config/default.json file contains base configuration:

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

Shop Settings
Extension Registration
Theme Configuration

Configure store-wide settings:

{
  "shop": {
    "language": "es",      // Store language (es, en, etc.)
    "currency": "USD",     // Default currency
    "timezone": "UTC",     // Store timezone
    "weightUnit": "kg"     // Weight unit (kg, lb)
  }
}

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

name: Unique extension identifier
resolve: Path to extension directory
enabled: Enable/disable extension

Set the active theme:

{
  "system": {
    "theme": "anasuplements"
  }
}

The theme must exist in themes/[name]/

Environment-Specific Configuration

{
  "system": {
    "port": 3000,
    "logLevel": "debug"
  },
  "database": {
    "logging": true
  }
}

Extension Setup

Each extension has its own configuration:

Extension Structure

extensions/productCatalog/
├── src/
│   ├── graphql/
│   │   └── types/ProductExtension/
│   │       └── ProductExtension.graphql
│   └── pages/
│       └── frontStore/productView/
│           └── SupplementInfo.tsx
├── package.json
└── tsconfig.json

Extension Package Configuration

{
  "name": "sample-evershop-extension",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "tsc": "tsc"
  }
}

Extension TypeScript Configuration

{
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ES2018",
    "lib": ["dom", "dom.iterable", "esnext"],
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "declaration": true,
    "sourceMap": true,
    "allowJs": true,
    "checkJs": false,
    "jsx": "react",
    "outDir": "./dist",
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "allowArbitraryExtensions": true,
    "strictNullChecks": true,
    "isolatedModules": false,
    "baseUrl": ".",
    "rootDir": "./src"
  },
  "include": ["src"]
}

Theme Setup

Current Theme: anasuplements

The active theme provides the visual layer:

themes/anasuplements/
├── src/
│   └── pages/
│       ├── all/              # Global components
│       │   ├── Header.tsx
│       │   └── Footer.tsx
│       ├── homepage/         # Homepage components
│       │   ├── Hero.tsx
│       │   ├── Features.tsx
│       │   └── FeaturedProducts.tsx
│       └── account/          # Account pages
│           ├── Dashboard.tsx
│           ├── Login.tsx
│           └── Register.tsx
├── package.json
└── tsconfig.json

Theme Configuration

Themes use the same TypeScript configuration as extensions. Each theme component exports:

// Required exports for page components
export default function MyComponent({ props }) {
  return <div>Content</div>;
}

export const layout = {
  areaId: 'content',       // Where to render
  sortOrder: 10            // Rendering order
};

export const query = `    // GraphQL query (optional)
  query {
    data {
      field
    }
  }
`;

Theme components should only contain presentation logic. Business logic belongs in extensions.

Production Deployment

Build for Production

Update Production Configuration

Edit config/production.json:

{
  "system": {
    "port": 80,
    "logLevel": "error"
  },
  "shop": {
    "url": "https://yourstore.com"
  }
}

Set Environment Variables

Update .env for production:

NODE_ENV=production
DB_HOST=your_production_host
DB_NAME=your_production_db
SESSION_SECRET=your_strong_random_secret

Build the Application

Compile all TypeScript and bundle assets:

npm run build

This compiles:

All extensions to .evershop/build/extensions/
All themes to .evershop/build/themes/
Creates optimized production bundles

Start Production Server

npm run start

Or use a process manager like PM2:

npm install -g pm2
pm2 start "npm run start" --name evershop
pm2 save
pm2 startup

Production Checklist

Security

Strong SESSION_SECRET in .env
PostgreSQL users with limited privileges
HTTPS enabled (use reverse proxy like Nginx)
Firewall configured (only ports 80/443 open)
Regular security updates

Performance

Database connection pooling configured
Static assets served via CDN
Gzip compression enabled
Database indexes optimized
Caching strategy implemented

Monitoring

Scalability

Troubleshooting

Database Connection Failed

Problem: Cannot connect to PostgreSQLSolutions:

# Check PostgreSQL is running
sudo systemctl status postgresql

# Verify credentials
psql -h localhost -U evershop_user -d evershop

# Check .env file
cat .env | grep DB_

# Test connection
pg_isready -h localhost -p 5432

Port Already in Use

Problem: Port 3000 is already occupiedSolutions:

Change port in config/default.json:

{
  "system": {
    "port": 3001
  }
}

Or kill the process using port 3000:

# Find process
lsof -i :3000

# Kill process
kill -9 <PID>

TypeScript Compilation Errors

Problem: Extension fails to compileSolutions:

# Navigate to extension
cd extensions/yourExtension

# Check TypeScript config
cat tsconfig.json

# Compile manually to see errors
npx tsc

# Clear build cache
rm -rf dist/
rm -rf ../../.evershop/build/

Extension Not Loading

Problem: Custom extension doesn’t appearSolutions:

Verify registration in config/default.json
Check extension is enabled: "enabled": true
Verify directory structure matches config
Restart development server
Check server logs for errors

GraphQL Schema Errors

Problem: GraphQL types not resolvingSolutions:

# Check .graphql file syntax
cat extensions/yourExt/src/graphql/types/YourType/YourType.graphql

# Verify resolvers exist
cat extensions/yourExt/src/graphql/types/YourType/YourType.resolvers.js

# Rebuild
npm run build

Next Steps

Development Guide

Learn how to build extensions and create custom functionality

Theme Customization

Customize the visual appearance of your store

API Reference

Explore the complete API documentation

GraphQL Schema

Learn about GraphQL types and queries

Additional ResourcesCheck the context/ directory in your project for detailed technical documentation in Spanish, including:

Architecture overview
Code standards
Testing guide
Deployment procedures

Get Started

Architecture

Core Concepts

Development Guides

Extensions

Themes

System Requirements

Runtime

Database

Package Manager

Build Tools

Installation Steps

Configuration Files

Package Configuration

Store Configuration

Environment-Specific Configuration

Extension Setup

Extension Structure

Extension Package Configuration

Extension TypeScript Configuration

Theme Setup

Current Theme: anasuplements

Theme Configuration

Production Deployment

Build for Production

Production Checklist

Troubleshooting

Next Steps

Development Guide

Theme Customization

API Reference

GraphQL Schema

Build docs developers (and LLMs) love

Get Started

Architecture

Core Concepts

Development Guides

Extensions

Themes

Documentation Index

​System Requirements

Runtime

Database

Package Manager

Build Tools

​Installation Steps

​Configuration Files

​Package Configuration

​Store Configuration

​Environment-Specific Configuration

​Extension Setup

​Extension Structure

​Extension Package Configuration

​Extension TypeScript Configuration

​Theme Setup

​Current Theme: anasuplements

​Theme Configuration

​Production Deployment

​Build for Production

​Production Checklist

​Troubleshooting

​Next Steps

Development Guide

Theme Customization

API Reference

GraphQL Schema

Build docs developers (and LLMs) love

System Requirements

Installation Steps

Configuration Files

Package Configuration

Store Configuration

Environment-Specific Configuration

Extension Setup

Extension Structure

Extension Package Configuration

Extension TypeScript Configuration

Theme Setup

Current Theme: anasuplements

Theme Configuration

Production Deployment

Build for Production

Production Checklist

Troubleshooting

Next Steps