Installation

Scaffold a new app

The fastest way to start is the project scaffolder, create-basalt. It generates a production-shaped app and only includes what you pick — nothing dead ships. Your package manager's create command downloads and runs it on the spot — nothing to install first:

pnpm create basalt my-saas
# or
npm create basalt my-saas
# or
yarn create basalt my-saas
# or
bun create basalt my-saas

Run it without a name in a terminal to answer prompts interactively (multi-tenancy, auth, billing, web UI, CLI, install, git). Pass flags to skip the questions:

Flag	Default	What it does
--no-tenancy	tenancy on	Skip multi-tenancy (@basaltkit/tenancy)
--no-auth	auth on	Skip authentication (@basaltkit/auth, APP_SECRET, /auth/*)
--billing	off	Include subscriptions/plans (@basaltkit/subscriptions)
--ui	off	Add a React + shadcn web/ frontend — see Web UI. Forces pnpm
--cli	off	Add the basalt CLI (make:* generators + built-in commands)
--install	off	Install dependencies at the end
--git	off	git init + an initial commit
--pm=<mgr>	autodetect	Force pnpm | npm | yarn | bun
--dir=<path>	./<name>	Destination folder
-y, --yes	—	Accept all defaults, no prompts

pnpm create basalt my-saas --billing --cli --install --git   # full stack, installed and committed
npm create basalt service-api --no-tenancy --no-auth         # minimal API

By default the scaffolder only writes files — it doesn't install dependencies or touch git unless you add --install / --git. So the usual next steps are:

cd my-saas
pnpm install
pnpm dev        # http://localhost:3000  (health check at /health)
pnpm test

The generated project boots an app with typed routes, structured logging, a health check and — unless you opted out — multi-tenancy (header and subdomain resolvers) and authentication. For a guided end-to-end run, see Getting Started.

--ui requires pnpm

The web/ frontend is a member of a pnpm workspace (pnpm-workspace.yaml), which npm, yarn and bun can't install or run. If you request --ui with another manager, the scaffolder switches to pnpm automatically.

Choose an HTTP adapter

Your routes are written once and run on any of three adapters — pick the one for your stack (see HTTP Adapters):

pnpm add @basaltkit/core @basaltkit/http @basaltkit/fastify fastify          # Fastify
pnpm add @basaltkit/core @basaltkit/http @basaltkit/express express          # Express
pnpm add @basaltkit/core @basaltkit/http @basaltkit/hono hono @hono/node-server  # Hono

Add to an existing app

Basalt packages work incrementally. To add multi-tenancy to an existing app, install just the pieces you need — it works the same on any adapter:

pnpm add @basaltkit/core @basaltkit/tenancy

Every package publishes ESM with types and follows the same plugin contract, so you adopt one capability at a time.

Requirements

• Node.js 22+
• pnpm (recommended) — the monorepo pins its version via packageManager
• For production: PostgreSQL (Prisma), and Redis for cache/queues when you enable them

Scaffold inside a project

Once you have an app, generate full resource verticals with the CLI generator:

basalt make:resource Project

This emits a schema, repository, service, DI plugin, typed CRUD routes and a test — all wired and ready to run.