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-kitFrom the repository root:
npm installcp .env.example .envnpm run db:migratenpm run devnpm 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-listingsDemo 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 --buildMigrations run once in a dedicated migrate service before the API starts. See Deploying for the full container and Railway story.
What you just started
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 componentsThe 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-serviceCommands you will actually use
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:portalNext
Make it yours: Configuration walks through portal.config.ts, the single file that defines your portal.