Quick Start

Get your EverShop e-commerce store up and running in minutes

Get Started in 5 Minutes

This guide will help you quickly set up and run your EverShop application locally.

Before you begin, ensure you have Node.js 18+ and PostgreSQL 12+ installed on your system.

Prerequisites

Verify you have the required software:

node --version  # Should be v18 or higher
npm --version   # Should be v9 or higher
psql --version  # Should be PostgreSQL 12 or higher

Quick Setup

1. Clone or Navigate to Your Project

   If you already have the project, navigate to it:

   cd my-evershop-app
   
2. Install Dependencies

   Install all required npm packages:

   npm install
   

   This installs:

   • @evershop/evershop (v2.1.1) - Core framework
   • TypeScript and type definitions
   • Development tools
3. Configure Database

   Create a .env file in the project root with your database credentials:

   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=evershop
   DB_USER=your_username
   DB_PASSWORD=your_password
   

   Never commit .env files to version control. The .gitignore is already configured to exclude them.

4. Run Initial Setup

   Initialize the database and install EverShop:

   npm run setup
   

   This command:

   • Creates database tables
   • Sets up initial data
   • Configures the system
5. Start Development Server

   Launch the development server with hot reload:

   npm run dev
   

   Your store will be available at:

   • Storefront: http://localhost:3000
   • Admin Panel: http://localhost:3000/admin

Available Commands

Here are the npm scripts configured in your package.json:

Development

# Start development server with hot reload
npm run dev

# Accessible at http://localhost:3000
# Changes to code automatically reload

# Build the project for production
npm run build

# Start production server
npm run start

# Or combine both commands
npm run build && npm run start

# Install and initialize EverShop
npm run setup

# Use this for first-time setup

Verify Installation

Once the development server is running, verify everything works:

Storefront

Open http://localhost:3000 in your browser. You should see:

• Homepage with featured products section
• Navigation header
• Product categories
• Footer with store information

The current theme (anasuplements) uses a green color scheme optimized for supplement products.

Admin Panel

Navigate to http://localhost:3000/admin:

• Log in with admin credentials (created during setup)
• Access product management
• Configure store settings
• Manage orders and customers

API

Test the GraphQL API at http://localhost:3000/graphql:

query {
  products(limit: 5) {
    items {
      productId
      name
      price
      description
    }
  }
}

Project Structure Overview

Understand your project’s organization:

my-evershop-app/
├── config/                    # Configuration files
│   ├── default.json          # Base settings
│   ├── development.json      # Dev environment
│   └── production.json       # Production environment
├── extensions/               # Custom extensions
│   ├── offlinePayments/     # Payment methods
│   ├── productCatalog/      # Product features
│   └── productReviews/      # Review system
├── themes/                   # Visual themes
│   └── anasuplements/       # Current active theme
├── .env                      # Environment variables (create this)
├── .evershop/               # Build output (DO NOT EDIT)
├── node_modules/            # Dependencies (DO NOT EDIT)
└── package.json             # Project dependencies

Important Directories

• ✅ Edit: config/, extensions/, themes/
• ❌ Never edit: .evershop/, node_modules/

Active Extensions

Your project comes with these pre-configured extensions:

offlinePayments

Adds cash on delivery and bank transfer payment methods

productCatalog

Extended product information system for supplements (ingredients, benefits, dosage)

productReviews

Customer review and rating system for products

All extensions are registered in 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
      }
    ],
    "theme": "anasuplements"
  }
}

Development Workflow

1. Make Changes

   Edit files in extensions/ or themes/:

   • TypeScript files (.ts, .tsx)
   • GraphQL schemas (.graphql)
   • Configuration files (.json)
2. Auto-Reload

   The development server automatically detects changes and reloads:

   • Backend changes rebuild the API
   • Frontend changes update the UI
   • No manual restart needed
3. Test Changes

   View your changes immediately:

   • Refresh your browser
   • Check the console for errors
   • Verify functionality

Example: View Sample Extension

Explore the sample extension to understand the structure:

extensions/sample/
├── src/
│   ├── api/createFoo/
│   │   ├── route.json                      # API route config
│   │   └── [bodyParser]createFoo.ts       # Endpoint handler
│   ├── pages/frontStore/homepage/
│   │   └── FooList.tsx                    # Page component
│   ├── crons/
│   │   └── everyMinute.ts                 # Scheduled job
│   └── bootstrap.ts                        # Extension init
├── package.json
└── tsconfig.json

View Sample API Endpoint

// extensions/sample/src/api/createFoo/[bodyParser]createFoo.ts
import { EvershopRequest, EvershopResponse } from '@evershop/evershop';

export default (request: EvershopRequest, response: EvershopResponse, next) => {
  const { name, description } = request.body;

  if (!name || !description) {
    return response
      .status(400)
      .json({ error: 'Name and description are required' });
  }

  const newFoo = {
    id: Date.now(),
    name,
    description
  };

  response.status(201).json({
    success: true,
    data: { foo: newFoo }
  });
};

With route configuration:

// extensions/sample/src/api/createFoo/route.json
{
  "methods": ["POST"],
  "path": "/foos",
  "access": "private"
}

Common Issues

Port 3000 already in use

If port 3000 is occupied, you can change it in config/default.json:

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

Database connection error

Verify your .env file has correct credentials:

# Check PostgreSQL is running
sudo service postgresql status

# Test connection
psql -h localhost -U your_username -d evershop

Module not found errors

Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

TypeScript compilation errors

Each extension has its own tsconfig.json. Check for type errors:

cd extensions/yourExtension
npm run tsc

Next Steps

Now that you have EverShop running:

Installation Guide

Learn about detailed configuration options and production setup

Development Guide

Build your first extension and customize your store

Theme Customization

Modify the visual appearance and create custom themes

API Reference

Explore the complete API documentation

Need Help?

Check the context/ directory in your project root for complete technical documentation in Spanish.