Skip to main content

Standalone App

Use this guide when you want to build a product or service on top of Open Saasframe without modifying the platform core. A standalone app pulls Open Saasframe packages from npm — your modules, overrides, and customisations live in your own repository.

If you need to modify the core itself, use the Monorepo guide instead.

Prerequisites​

1. Git​

xcode-select --install
# or via Homebrew after installing it (see below)

2. Homebrew​

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Node.js 26​

# Via Homebrew
brew install node@26
echo 'export PATH="/opt/homebrew/opt/node@26/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Or via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# Reopen terminal, then:
nvm install 26 && nvm use 26 && nvm alias default 26

Verify: node --version → v24.x.x

4. Yarn 4.12.0​

corepack enable
corepack prepare yarn@4.12.0 --activate

Verify: yarn --version → 4.12.0

5. Infrastructure services — Docker Desktop (recommended)​

The standalone app template includes a docker-compose.yml that starts PostgreSQL, Redis, and Meilisearch. Install Docker Desktop for Mac to use it.

Alternative — native PostgreSQL via Homebrew:

brew install postgresql@16
brew services start postgresql@16
createdb saasframe

Then set DATABASE_URL manually (see below).

Create and configure the app​

npx create-saasframe-app my-app
cd my-app

This scaffolds a new standalone app. Before starting, configure the environment:

cp .env.example .env

Edit .env and set at minimum:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/saasframe
JWT_SECRET=change-me-dev-secret
REDIS_URL=redis://localhost:6379

Generate a strong JWT_SECRET:

openssl rand -hex 32

Start the infrastructure services:

docker compose up -d

Bootstrap and start​

yarn setup

yarn setup installs dependencies, builds packages, generates registries, and runs yarn initialize (migrations + seeding). The admin credentials are printed at the end.

Then start the app:

yarn dev

Open http://localhost:3000/backend and sign in with the credentials printed during setup.

Run multiple persistent standalone apps against the same PostgreSQL server​

yarn setup, yarn dev, and friends accept an optional --database-name[=<name>] flag that rewrites the database segment of DATABASE_URL in ./.env. The flag is fully additive — without it, every script keeps its current behavior.

# explicit name; the script asks once whether to update .env (default yes)
yarn setup --database-name=client_a

# bare flag derives the database name from this app's folder
yarn setup --database-name

# one-off review run that does not edit .env
yarn dev --database-name=review_1720 --no-update-env

This makes it easy to run e.g. client-a/ and client-b/ side by side against the same PostgreSQL server without manually editing .env first. CI / non-interactive runs default to updating .env; pass --no-update-env (or set SF_DEV_DATABASE_UPDATE_ENV=false) to opt out.

Add your own modules​

Drop modules into src/modules/ and register them in src/modules.ts with from: '@app'. See the customisation guide for details.

Eject a core module for deep customisation​

When you need to modify the internals of a core module, eject it:

yarn saasframe eject --list       # see which modules support ejection
yarn saasframe eject currencies   # copy a module into src/modules/
yarn saasframe generate all
yarn dev

Release channels​

# Latest stable (default)
npx create-saasframe-app my-app

# Latest prerelease from the develop branch
npx create-saasframe-app@develop my-app

For a specific version: npx create-saasframe-app@x.y.z my-app

Full guide: customization/standalone-app