Documentation

Official guide for the create-stackforge-app CLI and generated monorepos. Maintainers: contributing. Prefer a visual picker? Build your command.

Introduction

create-stackforge-app scaffolds a production-ready pnpm monorepo: apps/web (Next.js 14 App Router), apps/api (NestJS), packages/contracts (shared Zod types), other shared packages, Prisma, PostgreSQL or SQLite, Tailwind + shadcn/ui, JWT auth, optional Docker, and generated CI.

Generated projects include pnpm scripts for stackforge doctor and info (via create-stackforge-app as a dev dependency). Run create with npx—no global install. Node.js 18+.

Quick start

Interactive scaffolding:

Project name and description
Database: PostgreSQL or SQLite
Docker support (yes/no)
Automatic dependency installation with pnpm (yes/no)
Default preset is dashboard (full stack); use --preset for minimal or api

npx create-stackforge-app@latest

Non-interactive mode

Use -y/--yes for defaults (PostgreSQL, Docker, auto-install, preset dashboard), or pass individual flags:

npx create-stackforge-app@latest my-app -y

npx create-stackforge-app@latest my-api -y --preset api

npx create-stackforge-app@latest my-app -y --database sqlite --no-docker --no-install

CLI flags

Flag	Description
-p, --preset <name>	dashboard (default), minimal, or api
-d, --database <type>	Database: postgresql or sqlite
--docker / --no-docker	Generate or skip Docker support
--install / --no-install	Install dependencies automatically or skip
-y, --yes	Skip all prompts and use defaults
-c, --cwd <path>	Working directory for the new project

Presets

Presets control how much is generated. Invalid preset names fail the CLI (no silent fallback).

dashboard — apps/web + apps/api with user admin, profile, settings (default)
minimal — apps/web + apps/api with auth and a simple dashboard (no user CRUD UI)
api — apps/api only (no Next.js app); full REST API including users module

npx create-stackforge-app@latest my-app -y --preset minimal

npx create-stackforge-app@latest my-api -y --preset api

stackforge doctor & info

From the root of a generated project. Plain npx stackforge does not work—there is no npm package named stackforge; use the scripts below (or the fallback for older scaffolds).

doctor — Node, pnpm, manifest, apps paths, DATABASE_URL, JWT_SECRET, Docker
info — StackForge version, preset, stack versions from package.json files

pnpm run doctor

pnpm run info

Generated project structure

packages/contracts — shared Zod schemas; Nest DTOs and web types stay aligned
JWT auth: register, login, /auth/me (dashboard & minimal include web auth UI)
Prisma schema and migrations under apps/api
Optional Prisma Studio in Docker (PostgreSQL, http://127.0.0.1:5555)
Projects from 1.2.x used frontend/ and backend/ (manifest v1) — see repo docs/MIGRATION-monorepo.md

my-app/
├── apps/
│   ├── api/          # NestJS
│   └── web/          # Next.js (omitted for --preset api)
├── packages/
│   ├── contracts/    # Zod schemas + shared API types
│   ├── typescript-config/
│   ├── eslint-config/
│   └── ui/           # shared stub
├── stackforge.json   # schema v2
├── docker-compose.yml
├── AGENTS.md
└── pnpm-workspace.yaml

Requirements

CLI: Node.js >= 18. Generated apps use pnpm workspaces—enable Corepack if pnpm is missing:

corepack enable

corepack prepare pnpm@9 --activate

Run locally

pnpm install generates the Prisma client automatically. For PostgreSQL with generated Docker support, start Postgres before db:setup; skip that command for SQLite or an existing PostgreSQL server.

Run pnpm dev from the project root so packages/contracts is built and watched alongside the apps.

cd my-app && pnpm install

cd my-app && docker compose up -d postgres # PostgreSQL + generated Docker only

cd my-app && pnpm run db:setup # prisma generate + migrate (first time)

cd my-app && pnpm dev

cd my-app && pnpm run doctor

Run the full Docker stack

Use this path only when Docker support was generated. Compose waits for PostgreSQL and the API container applies existing migrations before startup.

cd my-app && pnpm install

cd my-app && docker compose up --build -d

Troubleshooting

pnpm: command not found → run corepack enable and corepack prepare pnpm@9 --activate
Directory already exists and is not empty → choose another project name or clear the folder
Invalid --database → use postgresql or sqlite only
Invalid --preset → use dashboard, minimal, or api only
npx stackforge doctor fails → use pnpm run doctor from the project root, or npx --package=create-stackforge-app@latest stackforge doctor on older scaffolds
API TypeScript errors about prisma.user → ensure the database is running, then run pnpm run db:setup