Quick start

Get the Website (swapps-client) running locally in a few minutes.

Prerequisites

  • Node.js 20+ (the repo pins >=22.12.0 in package.json engines; Node 20 is the version used in CI). Use the version in .nvmrc.
  • npm 9+
  • Wrangler (installed as a dev dependency; a global install is optional)

Installation

  1. Clone the repository
git clone https://github.com/swappsco/swapps-client.git
cd swapps-client
  1. Install dependencies
npm install
  1. Set up environment variables
cp .env.example .env

Local-only build-time secrets (e.g. the reCAPTCHA site key) go in .dev.vars, which Vite loads into process.env at build time. See Environment setup for the full list of variable names.

Run the dev server

npm run dev

This starts wrangler dev --env dev on http://localhost:3000, serving the production-style Worker bundle with the dev environment variables from wrangler.toml.

npm run watch:dev

This runs scripts/watch-dev.ts, which rebuilds on file changes and reloads the browser. Use it for the best local iteration loop.

Watch mode (rebuild only)

npm run watch

Continuously rebuilds without starting a dev server (scripts/watch.ts).

Build for production

npm run build

The full pipeline runs, in order:

  1. scripts/build-static.ts — generate static files (sitemap inputs, etc.).
  2. tsc -b — TypeScript project build / type emit.
  3. vike build — build the Vike SSR bundle and client assets.
  4. scripts/patch-server-entry.ts — patch the generated Vike server entry.
  5. scripts/copy-static.ts — copy static files into dist.
  6. scripts/build-worker.ts — bundle src/worker.ts into dist/worker.js with esbuild.

See Build and styling for details.

Deploy

npm run deploy

Runs wrangler deploy against the default (production) environment. For preview deployments and CI, see Deployment.

Common issues

Port already in use

The default dev port is 3000. If it is busy, stop the conflicting process or change the port via the --port flag in the dev script.

Service binding not available locally

When running locally without the Platform Worker, API calls fall back to plain HTTP against API_URL. This is expected — see Service bindings.

Useful commands

Command Purpose
npm run dev Wrangler dev server on port 3000 (--env dev)
npm run watch:dev Rebuild + dev server + browser reload (recommended)
npm run watch Rebuild production bundle on change (no server)
npm run build Full production build pipeline
npm run lint ESLint
npm run type-check tsc --noEmit
npm run test Run tests (Vitest)
npm run deploy wrangler deploy
npm run preview Build with preview env + upload a versioned preview

Next steps