Getting Started
Installation
Set up the CommerceJS monorepo and install all dependencies.
CommerceJS uses a pnpm monorepo. All packages live under the packages/ directory and share a common build toolchain.
Prerequisites
You need the following tools installed:
- Node.js 22 or later
- pnpm 9 or later
Clone and Install
Clone the repository
git clone https://github.com/commerce-js/commerce.js.git
cd commercejs
Install dependencies
pnpm install
Build all packages
The packages depend on each other, so build them in order:
pnpm --filter @commercejs/types build
pnpm --filter @commercejs/core build
pnpm --filter @commercejs/checkout build
pnpm --filter @commercejs/payment-tap build
pnpm --filter @commercejs/webhook-verifier build
pnpm --filter @commercejs/adapter-salla build
pnpm --filter @commercejs/platform build
pnpm --filter @commercejs/nuxt build
You can also build everything at once with
pnpm -r build, but the ordered approach is more reliable for the first build.Environment Setup
The platform and hosted checkout applications require environment variables. Create .env files:
packages/platform/.env
DATABASE_URL="postgres://user:pass@ep-xxx.neon.tech/commerce"
ADMIN_EMAIL="admin@store.com"
ADMIN_PASSWORD="your_password"
apps/hosted-checkout/.env
TAP_SECRET_KEY="sk_test_your_key_here"
TAP_PUBLIC_KEY="pk_test_your_key_here"
TAP_BASE_URL="https://api.tap.company/v2"
TAP_MERCHANT_ID="your_merchant_id"
APP_URL="http://localhost:3100"
DATABASE_URL="postgres://user:pass@ep-xxx.neon.tech/commerce"
Get your test keys from the Tap Dashboard. The
APP_URL is used for payment redirects and webhook URLs. DATABASE_URL should be a Neon Postgres connection string.Run the Hosted Checkout
Start the development server for the hosted checkout application:
cd apps/hosted-checkout
pnpm dev
The checkout page is available at http://localhost:3100.
Monorepo Structure
commercejs/
├── packages/
│ ├── types/ # @commercejs/types
│ ├── core/ # @commercejs/core (orchestration engine)
│ ├── checkout/ # @commercejs/checkout
│ ├── payment-tap/ # @commercejs/payment-tap
│ ├── webhook-verifier/ # @commercejs/webhook-verifier
│ ├── adapter-salla/ # @commercejs/adapter-salla
│ ├── adapter-medusa/ # @commercejs/adapter-medusa
│ ├── platform/ # @commercejs/platform (Neon Postgres engine)
│ ├── nuxt/ # @commercejs/nuxt (Nuxt module)
│ ├── ui/ # @commercejs/ui (eCommerce components)
│ ├── delivery-armada/ # @commercejs/delivery-armada
│ ├── delivery-parcel/ # @commercejs/delivery-parcel
│ ├── storage-s3/ # @commercejs/storage-s3
│ ├── notification-resend/ # @commercejs/notification-resend
│ ├── notification-smtp/ # @commercejs/notification-smtp
│ ├── analytics-ga/ # @commercejs/analytics-ga
│ ├── cloud/ # @commercejs/cloud
│ └── cli/ # @commercejs/cli
├── apps/
│ ├── hosted-checkout/ # Hosted checkout application
│ ├── storefront/ # Reference storefront
│ ├── dashboard/ # Commerce.js Cloud dashboard
│ └── docs/ # Documentation site
├── pnpm-workspace.yaml
└── package.json