Documentation

Quickstart

Clone Frontstead Kit and get a portal and API running locally in four commands.

This page takes you from nothing to a running portal on your own machine. It should take about five minutes, most of which is npm install.

Prerequisites

Three things, and no more:

  • Node.js 22.12
  • npm — the repository uses npm workspaces, so npm specifically
  • PostgreSQL — required and authoritative

Redis and Typesense are optional and are not required for a local or production baseline. Search falls back to PostgreSQL when Typesense is not configured.

Clone and run

git clone https://github.com/frontstead/frontstead-kitcd frontstead-kit

From the repository root:

npm installcp .env.example .envnpm run db:migratenpm run dev

npm run dev starts both services:

Service URL
Portal http://localhost:3006
API http://localhost:3001

That is the whole loop. npm run dev:portal is the explicit equivalent of the default.

An empty database is valid

npm run db:migrate also creates your portal from portal.config.ts (the stock abc-realty until you change it), so the portal works on an empty database. You do not need demo data, MLS credentials, or an MLS board to see the application working — those are deliberately separate steps. The same step creates your portal in production; see Going live.

If you do want local demo data, you have to name the database you are seeding first. The guard is the URL host and database name, with the scheme and credentials excluded:

export CONFIRM_DEMO_SEED='localhost:5432/frontstead_dev?schema=public'npm run db:seed:portalnpm run db:seed:demo-listings

Demo seeds refuse to run in production. Do not set CONFIRM_DEMO_SEED as a production service variable.

Demo output is for local evaluation only. Create real users through the application rather than relying on documented fixed credentials.

Prefer containers

Docker Compose is the canonical portable deployment baseline:

docker compose up --build

Migrations run once in a dedicated migrate service before the API starts. See Deploying for the full container and Railway story.

What you just started

Project shape
apps/  portal/         Default public frontend  api/            Express API  mls-service/    Included MLS synchronization worker  typesense/      Optional search service toolingpackages/  db/             Prisma schema, migrations, and guarded demo seeds  api-client/     Shared API URL and client utilities  portal-config/  Portal policy and configuration  search/         PostgreSQL fallback and optional Typesense integration  cache/          Optional Redis integration  email/          Transactional email support  tokens/         Shared design tokens  ui/             Shared UI components

The MLS worker is a separate long-running process and stays idle until you configure a vendor. Run it on its own when you need it:

npm run dev --workspace=@frontstead/mls-service

Commands you will actually use

Common commands
npm run dev                 # portal + APInpm run dev:api             # API onlynpm run db:migrate          # apply existing PostgreSQL migrationsnpm run test:apinpm run test:portalnpm run typecheck:apinpm run typecheck:portal

Next

Make it yours: Configuration walks through portal.config.ts, the single file that defines your portal.