Documentation

Nōksha Commerce

A production-grade, scalable e-commerce platform with a runtime multi-vendor toggle. Three apps — storefront, admin/seller console, and a Node API — in a single Turborepo, sharing database, auth, types, and UI. Thank you for your purchase!

Features

Requirements

• Node.js 24 LTS and pnpm 11 (npm i -g pnpm)
• PostgreSQL 14+ — local via Docker (included) or a managed DB (Neon, Supabase, RDS…)
• Docker Desktop (optional, for the bundled local Postgres)
• A Stripe account (test keys are fine to start)
• A Google Cloud OAuth client (optional — for "Sign in with Google")
• A Cloudinary or ImageKit account (optional — image hosting in production)
• A Resend or SMTP account (optional — transactional email)

Quick start

Get a fully-seeded store running locally.

# 1. Install dependencies
pnpm install

# 2. Create your env file and fill in values (see Configuration)
cp .env.example .env

# 3. Start a local Postgres (or point DATABASE_URL at your own)
docker compose up -d postgres

# 4. Set up the database + demo data
pnpm db:generate
pnpm db:migrate
pnpm db:seed                 # store settings, categories, demo product
pnpm seed:admin              # creates the admin user
pnpm seed:catalog            # full demo catalog

# 5. Run everything (storefront + admin + API)
pnpm dev

Installation

1. 1. Unzip & install. Extract the package, then pnpm install at the root. This is a pnpm monorepo — always use pnpm.
2. 2. Environment. cp .env.example .env and fill values. The app boots with placeholders (features degrade gracefully) so you can start before every key is set.
3. 3. Database. Point DATABASE_URL at any Postgres. Locally, docker compose up -d postgres starts one for you.
4. 4. Migrate & seed. pnpm db:migrate creates the schema; the db:seed / seed:admin / seed:catalog scripts load demo data.
5. 5. Run. pnpm dev runs all three apps with hot reload.

Configuration

All configuration is via .env. Key variables:

See .env.example for the full, commented list.

Third-party services

Stripe (payments)

1. Create test keys at dashboard.stripe.com/apikeys → set STRIPE_SECRET_KEY + the two publishable vars.
2. Add a webhook endpoint → <api>/api/webhooks/stripe, event payment_intent.succeeded (and friends) → copy the signing secret into STRIPE_WEBHOOK_SECRET.
3. The webhook secret must match the key mode (test secret for test keys).

Google OAuth (optional)

1. console.cloud.google.com → APIs & Services → Credentials → OAuth client (Web).
2. Authorized redirect URI: <api>/api/auth/callback/google.
3. Set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET.

Media & Email (optional)

Set STORAGE_PROVIDER=cloudinary + CLOUDINARY_URL for production image hosting, and EMAIL_PROVIDER=resend + RESEND_API_KEY for emails. Both default to dev-safe modes (local disk / console).

Project structure

apps/
  web/      Storefront (Next.js 16, App Router)
  admin/    Admin & seller console (Next.js 16)
  api/      API hub (Hono) — runs on Node and Cloudflare Workers
packages/
  db/       Prisma schema, client, migrations, seeds
  auth/     Better Auth config (single source) + client
  types/    Zod schemas + shared TypeScript types
  core/     Pure business logic: cart, pricing, orders, inventory
  ui/       Shared themed shadcn/ui components + design tokens
  config/   Shared tsconfig / eslint / prettier / tailwind preset

One source of truth: models, contracts, and validation live in packages/*; the apps import them.

Development

Admin guide

• Sign in at the admin app with the seeded admin account, then change the password.
• Catalog — create products, variants (size/color), images, collections, categories.
• Orders — move orders through pending → paid → processing → fulfilled → shipped → delivered; refund/cancel.
• Customers — view accounts & orders. Newsletter subscribers are listed too.
• Store settings — currency, languages, and the multi-vendor toggle (off = single-brand B2C; on = marketplace with seller onboarding & payouts).
• Staff roles (RBAC) — admin, manager, warehouse, delivery, support — each scoped by a permission matrix.

Customization

Branding & theme

All design tokens (colors in OKLCH, fonts, radius) live in packages/config/tailwind/preset.css (the @theme block). Change them once and every app updates. Replace the logo/marks in packages/ui and apps/*/src/app/icon.svg.

Content

Catalog, collections, banners, and CMS pages are managed from the admin or seeded via the seed:* scripts in apps/api/scripts.

Currency & language

Enabled currencies/locales are set in Store settings; message catalogs live in apps/web/messages/*.json.

Deployment

Cloudflare Workers (recommended, free tier)

The API runs as a Worker; the Next apps deploy via OpenNext. Set your Postgres on Neon, your own domain on Cloudflare, then:

pnpm dlx wrangler@4 login          # one time
cd apps/api && wrangler secret put DATABASE_URL   # + the other secrets
pnpm cf:deploy:all                 # api + web + admin

The full Cloudflare runbook (DNS, routes, the Prisma-on-Workers + Neon settings, edge caching) ships in docs/cloudflare-deployment.md.

Vercel / Node host

The Next apps deploy to Vercel unchanged; the Hono API runs on any Node host (Render, Fly, Railway) with a Postgres URL. See DEPLOYMENT.md.

Go-live security checklist

• ☐ Set a strong, unique BETTER_AUTH_SECRET (never the dev default)
• ☐ Use live Stripe keys + a live webhook secret; verify a real payment + the order webhook
• ☐ Change the seeded admin password; remove demo/test accounts
• ☐ Set real NEXT_PUBLIC_*_URL origins (drives CORS + trusted origins)
• ☐ Put the DB behind SSL (sslmode=require); never expose it publicly
• ☐ Replace demo media with your own licensed images
• ☐ Confirm rate limits + HTTPS are active on the API

Built-in: Stripe webhook signature verification, Zod input validation at every boundary, server-side authorization on protected routes, and rate-limited auth endpoints.

Troubleshooting

Support & license

Your purchase includes item support per the Envato terms. For help, use the item's support tab / comments on the marketplace and include your steps, environment, and any error output.

Use of this item is governed by the Envato Market license you purchased (Regular or Extended). One license = one end product. See LICENSE.md. Thank you for choosing Nōksha — happy selling!