Getting Started with ShopNex

Welcome to ShopNex, the open-source eCommerce platform built on top of Payload CMS . This guide will help you set up your self-hosted store in just a few minutes using our CLI tool.

Whether you’re building a simple store or a large commerce platform, ShopNex gives you a strong foundation with modern technologies and powerful customization options.

🧱 Requirements

Before you begin, make sure you have the following installed:

Node.js (v18 or later)
pnpm or npm
Git

⚙️ Setup Steps

Use the official CLI to generate your project:

pnpm

bash pnpm dlx create-shopnex-app

You’ll be guided through the setup process, including:

Naming your project
Selecting a database (e.g., MongoDB or PostgreSQL)
Choosing optional features
Configuring environment variables

🏪 Choose Your Storefront

ShopNex supports flexible frontend integrations. You can choose between:

🧱 Builder.io (Visual Storefront)

To use Builder.io as your storefront:

Add your Builder.io credentials in the .env file.
Run the following command to seed example pages:


pnpm run pages:seed

CLI Options

The CLI accepts optional flags to customize your installation:

Flag	Description
`--fresh`	Skip seeding example data for a clean setup
`--skip-env`	Skip environment variable setup (you can configure `.env` manually later)
`--skip-dev`	Prevents the development server from auto-starting after setup

Example usage:


pnpm dlx create-shopnex-app my-store --fresh --skip-env

📁 Project Structure

Here’s an overview of the core folders in your new ShopNex project:

- payload-types.ts
- payload.config.ts
- plugins.ts

✨ Features Overview

✅ Analytics Dashboard – View sales and store performance metrics
🎨 Custom Branding – Style your store with Tailwind and custom admin theming
💳 Stripe Checkout – Secure, modern payment flow
🛒 Visual Storefront – Optional Builder.io integration
📦 Dropshipping Integration – Native support for CJ Dropshipping
📁 Order Management – View and manage orders and customer data
🧩 Plugin Marketplace – Extend functionality with installable plugins
🗂️ Data Import – CSV/Excel import mapping
🔗 Monorepo Support – Easy plugin and workspace management

🛠️ Contributing

We love community contributions!

⭐ Star the GitHub repo
🐛 Report bugs or request features via GitHub Issues
🔧 Fork the repo and submit a pull request
💬 Join the community on Discord

Before contributing, please:

Check open issues and PRs
Follow project-specific contribution guidelines