Quickstart

Get zap.ts running on your computer in five commands. You do not need any paid account to start.

This page takes you from a fresh copy of zap.ts to a running app.

You do not need a payment account, a storage account or an email provider. You do not need to create a settings file. Everything you need runs on your own computer.

Before you start

You need two programs installed:

Node.js, version 24 or newer. It runs JavaScript on your computer.
Docker, with Docker Compose. It runs the database and two other services for you, so you do not have to install them one by one.

On a Mac, Colima is the easier way to get Docker. It is free, it does not run a desktop app in the background, and it uses less memory than Docker Desktop.

brew install colima docker docker-compose
colima start

Run colima start once after each restart of your Mac. Every docker command on this page then works exactly as written.

zap.ts uses pnpm to install code libraries. You do not install pnpm yourself. Node.js ships with a tool called Corepack that does it for you:

corepack enable

Run that once. From then on, pnpm works inside zap.ts.

Corepack reads the packageManager line in package.json and uses exactly the pnpm version written there. So everyone on your team runs the same version, and nobody has to check which one.

The five commands

Run these in order, from the zap.ts folder.

pnpm install
docker compose up -d
pnpm run db:migrate
pnpm run db:seed
pnpm run dev:web

Here is what each one does.

pnpm install downloads every library the project needs.
docker compose up -d starts three services in the background: the database, an email inbox and a file store.
pnpm run db:migrate creates the tables inside the database.
pnpm run db:seed fills those tables with example data, so the app is not empty when you open it.
pnpm run dev:web starts the app.

Open localhost. The app is running.

What Docker started for you

Service	What it is	Where to look
Postgres	The database. It stores your data.	Port 5432
Mailpit	A fake email inbox. Emails your app sends land here instead of a real address.	localhost
MinIO	A file store. Uploads go here instead of a paid cloud service.	localhost

Payments run in test mode. The billing page says so on screen. No real card can be charged.

Starting the other apps

zap.ts holds six apps. Each one starts with its own command.

pnpm run dev:marketing   # your public website, port 3001
pnpm run dev:docs        # your product docs, port 3002
pnpm run dev:admin       # your back office, port 3003
pnpm run dev:emails      # preview your emails, port 3004
pnpm run dev:api         # the API server, port 8787

You can run several at the same time, each in its own terminal window.

Adding your own accounts later

Nothing needs a real account until you want one.

When you are ready to connect a real service, put your keys in a file named .env.local. Place it next to the .env.schema file that lists those keys. .env.local files are never saved to git, so your keys stay private.

See Environment for how this works.

If something does not work

The most common problem is that Docker is not running. Check that first.

See Troubleshooting for the other common problems.

Local development — working day to day
Project structure — what each folder holds
Environment — how settings and keys work
Add a feature — build your first feature