Installation guide
The following installation guides will guide you step-by-step to create a new EverShop project and get it started.
Please check this document for the system requirements list.
Install EverShop Using create-evershop-app command
npx create-evershop-app my-evershop-app
The create-evershop-app command will create a new folder named my-evershop-app and install all of the dependencies for you.
Install EverShop Using Docker
You can get started with EverShop in minutes by using the Docker image. The Docker image is a great way to get started with EverShop without having to worry about installing dependencies or configuring your environment.
curl -sSL https://raw.githubusercontent.com/evershopcommerce/evershop/main/docker-compose.yml > docker-compose.yml
docker-compose up -d
The Docker image will start a fresh EverShop installation with the default configuration. You can access the site at http://localhost:3000 and the admin panel at http://localhost:3000/admin.
To create a new admin user, terminal into the Docker app container and run the following command:
npm run user:create -- --email "your email" --password "your password" --name "your name"
The public Docker image is for installing EverShop in your local environment only. If you are looking for a development solution, please check the development section below.
Install EverShop manually using Npm
Step 1: Install The @evershop/evershop Npm Package
@evershop/evershop is the core of the EverShop platform. It contains all of the core modules like catalog, checkout, order.
npm init --init-type=module -y
npm install @evershop/evershop
EverShop is an ES-modules (ESM) project and requires "type": "module" in your project's package.json. npm 11 and newer write "type": "commonjs" into the package.json generated by npm init -y — with that value, npm run build fails on every page with Module parse failed: 'import' and 'export' may appear only with 'sourceType: module'. The npm pkg set type=module command sets the correct module type. Projects created with create-evershop-app already have it.
Step 2: Install the core Npm scripts
Open the package.json file and add the following scripts:
{
"scripts": {
"setup": "evershop install",
"build": "evershop build",
"start": "evershop start",
"dev": "evershop dev",
"seed": "evershop seed",
"start:debug": "evershop start --debug",
"user:create": "evershop user:create",
"user:changePassword": "evershop user:changePassword",
"theme:create": "evershop theme:create",
"theme:active": "evershop theme:active",
"theme:twizz": "evershop theme:twizz",
"theme:status": "evershop theme:status",
"theme:uninstall": "evershop theme:uninstall",
"theme:export-content": "evershop theme:export-content"
}
}
The six theme:* scripts are required if you plan to work with themes — creating one, activating it, or overriding its components. The theme documentation refers to them by their npm run names. See the Command-Line Interface reference for what each one does and which flags it accepts.
When you pass flags through npm run, separate them with --, e.g. npm run theme:active -- boutique --dry-run.
Step 3: Run the installation script
Before running this script, make sure that you have an empty Postgres database ready for EverShop.
Please check this document for the system requirements list.
The interactive setup wizard will prompt you for:
- Database connection details — host, port, database name, user, and password
- Admin user details — full name, email, and password (minimum 8 characters, must contain at least one letter and one digit)
Once you provide this information, the setup script will:
- Create a
.envfile in your project root with the database connection settings - Create the
mediaandpublicdirectories - Set up the database schema (create all required tables)
- Run all database migrations
- Create your administrator account
npm run setup
The .env file created by the setup script contains your database credentials:
DB_HOST="localhost"
DB_PORT="5432"
DB_NAME="evershop"
DB_USER="postgres"
DB_PASSWORD="your_password"
DB_SSLMODE="disable"
You can edit this file later to change your database connection settings. See the Database documentation for more options including SSL configuration.
Step 4: Folder permission
EverShop needs to write some files to the disk. So you need to make sure that the following folders have the write permission:
public/.evershop.logmedia
Step 5: Run the build command to build the site
npm run build
Step 6: Run the start command to start your store in production mode
npm run start
Your site will start at http://localhost:3000.
Admin panel can be accessed at http://localhost:3000/admin.
By default EverShop will start at port 3000. You can change the port by setting the PORT environment variable.
Configuring Your Store
Most of what a merchant changes day to day is not a config.json key. Currency, timezone, weight and length units, store languages, branding (logo, favicon), catalog display options, tax rounding and the cloud file-storage provider are all stored in the database and edited from Admin → Settings. They take effect without a restart and without a rebuild.
config/<env>.json stays for deployment concerns: database credentials, the active theme, session secrets and extension wiring — things a developer sets and a redeploy changes.
See Store Settings for the full split, the getSetting / getSettingSync API, and how to migrate extension code that still reads a config key.
Upgrade EverShop
To upgrade EverShop to the latest version:
npm install @evershop/evershop@latest
npm run build
npm run start
Database migrations are run automatically when the application starts, so any schema changes in the new version are applied for you.
A minor or patch upgrade is normally a drop-in replacement. A major upgrade is not: the core React version, component APIs and public import paths can change, and your custom theme and extensions run against them.
Before upgrading a live store, read the release notes for the version you are moving to, upgrade a staging copy first, and take a database backup — migrations are applied automatically on the first start and are not reversible.
The most recent example is EverShop 2.2, which moved the framework from React 17 to React 19. Most of those changes fail silently at runtime rather than at build time. See Upgrading To React 19 for the full list of breaking changes and the fix for each one.
Demo Data Seeding
After installation, you can populate your store with demo data using the seed command. This is useful for development and testing.
npm run seed
This command will populate your store with sample products, categories, and other data.
Demo data seeding is intended for development and testing environments only. Do not use it in production.
For Developers
If you are a developer and want to start the project in development mode, there are some additional steps you need to follow.
Install Additional Dev Dependencies
To run the project in development mode, you need to install additional dependencies. These are not required for production but are essential for development:
npm install --save-dev @types/node typescript @parcel/watcher @types/config @types/express @types/pg @types/react execa
Adding the workspace configuration
Open the package.json and add the following configuration:
{
"workspaces": ["extensions/*", "themes/*"]
}
This allows each extension and theme to function as an independent package with its own dependencies.
Start the project in development mode
npm run dev
Your store will start at http://localhost:3000 with hot-reloading enabled. Changes to React components update instantly in the browser.
The debug mode
The start:debug script (already added in Step 2) starts the production server with debug logging enabled:
npm run start:debug
This outputs detailed middleware execution timings and request processing information.
Debug mode is enabled by default when you run the dev command, so you don't need to use start:debug during development.
Dockerize Your Project
Dockerizing your EverShop project allows you to create a portable, self-contained environment for your application. Below is a guide to creating your own Docker image and managing persistent data like media files.
Handling Persistent Media Files
When you dockerize your application, it's crucial to handle the media directory correctly. This directory contains user-uploaded files (like product images) and should not be copied directly into the Docker image. If you do, any uploaded files will be lost whenever the container is rebuilt.
There are two primary approaches for managing media files:
-
Docker Volumes: This approach mounts a directory from your host machine into the container. Files are stored on the host, so they persist even if the container is removed. This is suitable for single-server deployments or local development.
-
Cloud Storage: This approach uses a cloud storage service like Amazon S3, Azure Blob Storage or Google Cloud Storage. This decouples file storage from your application container entirely, which is essential for auto-scaling environments and provides better durability and performance.
For any production environment, we strongly recommend using cloud storage. This approach is more scalable, reliable, and secure than using local volumes. It prevents data loss, simplifies backups, and is essential if you ever plan to run your application across multiple servers.
Amazon S3, Azure Blob Storage and Google Cloud Storage are built into EverShop core — there is no extension to install. Pick the provider in Admin → Settings → File Storage and fill in its credentials there, or pin them from config/<env>.json or environment variables when your infrastructure manages them. The S3 provider also drives any S3-compatible service (Cloudflare R2, MinIO, DigitalOcean Spaces) through a custom endpoint.
See File Storage for the provider settings, the credential precedence rules, and how to register a provider of your own.
1. Building Your Docker Image
Here is an example Dockerfile. Note that we have removed the COPY media ./media line.
FROM node:20-alpine
WORKDIR /app
RUN npm install -g npm@10
COPY package*.json .
# Copy your custom theme.
COPY themes ./themes
# Copy your custom extensions.
COPY extensions ./extensions
# Copy your config.
COPY config ./config
# DO NOT copy the media folder. It will be handled by a volume.
# Copy your public files.
COPY public ./public
# We must copy translations to the image as they are required for the build.
COPY translations ./translations
# Run npm install.
RUN npm install
# Build assets.
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "start"]
2. Using Docker Compose with a Volume
This docker-compose.yml file demonstrates how to build the image and attach a volume for the media directory.
version: "3.8"
services:
app:
build:
context: .
dockerfile: Dockerfile
restart: always
volumes:
- ./media:/app/media # Mounts the host's media folder to the container
environment:
DB_HOST: database
DB_PORT: 5432
DB_PASSWORD: postgres
DB_USER: postgres
DB_NAME: postgres
networks:
- myevershop
depends_on:
- database
ports:
- 3000:3000
#The postgres database:
database:
image: postgres:16
restart: unless-stopped
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
POSTGRES_PASSWORD: postgres
POSTGRES_USER: postgres
POSTGRES_DB: postgres
ports:
- "5432:5432"
networks:
- myevershop
networks:
myevershop:
name: MyEverShop
driver: bridge
volumes:
postgres-data:
With this configuration, any files uploaded to your application will be saved in the media folder on your host machine, ensuring they are not lost.
Support us
EverShop is an open-source project that relies on community support. If you find our project useful, please consider sponsoring us.