Local Development

Run the project on your computer to configure it, create your database schema, and customize it before deploying.

Do I have to do this? You can deploy to Vercel without ever cloning the repository, but the helper commands — npm run setup, npm run db:setup, npm run seed — only run from a local clone.

Without a clone you do the same work by hand: paste the migrations from supabase/migrations/ into the Supabase SQL Editor, and create your admin account by signing up through your own storefront and then setting is_admin = true on your row in Supabase → Table Editor → profiles. Cloning is the shorter road.

Step 1. Install Node.js 20 or newer

ShipCommerce requires Node.js 20 or newer. On Node 18 the build fails with a confusing error rather than a clear version message, so check this first. Download the LTS release from nodejs.org and follow the installer — no special settings needed.

Or install via terminal:

# macOS (Homebrew) — installs the current release, which is 20+
brew install node

# Windows / Linux (nvm)
nvm install 20
nvm use 20

Verify the version:

node -v
# Must print v20.x.x or higher

Seeing v18 or lower? Upgrade before continuing. Every later step on this page will fail otherwise, and the error messages won't point at the version.

Step 2. Download the project

After purchase you receive an invitation to your own copy of the repository. Clone that — the URL is on your invitation and looks like https://github.com/your-org/your-store.git:

git clone <your-repository-url>
cd <your-repository-name>

If your invitation gives you access to the upstream repository directly, that is github.com/ShipCommerce/ShipCommerce:

git clone https://github.com/ShipCommerce/ShipCommerce.git
cd ShipCommerce

Don't have Git? Download it from git-scm.com. On Mac, it's pre-installed. Keep the clone as a real Git repository — updates are applied with git merge.

Step 3. Install dependencies

In your terminal, make sure you're in the project folder, then run:

npm install

This downloads all the libraries the project needs. It takes about 1–2 minutes.

Step 4. Run the setup wizard

npm run setup

The wizard asks for your Supabase details and store name, generates a CRON_SECRET if you leave it blank, and writes .env.local for you. Stripe, email, AI, and analytics are all offered as optional and can be skipped — press Enter past them and add them later.

Have your Supabase project open in another tab; you'll be asked for its URL, its two API keys, and its database connection string. The Configuration page says exactly where each one lives in the dashboard.

Prefer editing the file yourself? Run cp .env.example .env.local and fill in the values by hand. The example file is annotated with the same links, and the Configuration page lists every variable.

Important: Never share or commit .env.local. It contains your secret keys.

Step 5. Create the database and admin account

Your Supabase project is empty until you run the migrations. Skip this and the site will load against a database with no tables.

npm run db:setup

This reads SUPABASE_DB_URL from .env.local and applies the migrations in supabase/migrations/ — tables, database functions, Row Level Security policies, and the storage bucket. It is idempotent, so re-running it is safe.

Then create your admin account:

npm run seed

This creates an admin user with the credentials admin@demo.com / Demo1234!, which is how you first get into /admin.

Change that password immediately — before the site is reachable from the internet. The default is published in these docs, so anyone can try it.

Step 6. Start the project

npm run dev

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

No Stripe account yet? That's fine. Cash on delivery and bank transfer work out of the box, so you can browse the store, add products, and place a real test order with nothing configured but Supabase. Add card payments whenever you're ready — see Configuration.

Useful commands

Command	What it does
npm run setup	Interactive wizard that writes `.env.local`. Re-run it any time to add optional services.
npm run db:setup	Creates the schema, policies, and storage bucket from `supabase/migrations/`. Safe to re-run.
npm run seed	Creates the admin user `admin@demo.com` / `Demo1234!`. Change the password right after.
npm run stripe:setup	Registers the Stripe webhook for your deployed site and saves the signing secret. Not for localhost.
npm run stripe:listen	Forwards Stripe webhooks to `localhost:3000` and prints a signing secret. Needs the Stripe CLI.
npm run post-deploy	Checks that critical variables are set and warns if Stripe is still in test mode.
npm run dev	Start the development server on port 3000.
npm run build	Production build. Run it before deploying to catch errors early.
npm run type-check	TypeScript check without producing a build. Fast way to validate edits.
npm run lint	Check code quality and style.
npm run test	Run the unit test suite.

Next: Set Up Database →