business-stack

Single npm package bundling a Next.js app, Hono gateway (Better Auth, integrations, authenticated proxy to FastAPI), and FastAPI backend. Turborepo runs web, gateway, and backend together.

Prerequisites

Install these on your machine and ensure they are on your PATH:

| Tool | Purpose | |------|---------| | Node.js 20+ | Runs the business-stack CLI | | npm (comes with Node) | business-stack start / dev use npm install and npm run for workspaces and Turborepo | | (optional) Bun | Only if you develop the full monorepo from git (bun run dev at repo root); not required for the published business-stack package | | uv | Installs and runs the Python backend | | Python 3.12 | Required by the backend (managed via uv) |

Check your environment:

npx business-stack doctor

Using npx (no install, or one-off runs)

npx runs the same business-stack binary as a global or local install. Use a version tag so npm does not cache an old release:

npx --yes business-stack@latest doctor
npx --yes business-stack@latest setup --yes
npx --yes business-stack@latest start

On Windows Command Prompt, use the same commands; if npx is slow the first time, it is downloading the package.

Quick start

From a folder with a package.json (create one with npm init -y if needed):

npm install business-stack
npx business-stack doctor
npx business-stack setup --yes
npx business-stack start

• setup writes secrets to gateway/auth.sqlite (stack_secrets) and creates gateway/.env, frontend/web/.env.local, and backend/.env under the installed package tree.
• start runs npm install, uv sync, Better Auth migrate (gateway SQLite), Alembic, then npm run start. The package is pre-built, so npm run build is skipped. Flags: --skip-install, --skip-build, --skip-migrate.

business-stack dev needs full monorepo sources; use bs for a terminal client against the running web origin:

bs --help

Set BUSINESS_STACK_WEB_URL (or NEXT_PUBLIC_AUTH_BASE_URL) to your Next URL (default http://localhost:3000). On PowerShell, bs -- --help if the shell intercepts flags.

Optional package.json scripts: "stack:start": "business-stack start" (and doctor / setup). Local install adds node_modules/.bin/business-stack and bs.

Global install (optional)

If you want the business-stack command on your PATH for every shell:

npm install -g business-stack
business-stack doctor
business-stack setup --yes
business-stack start

Files and secrets are then under your global npm prefix (for example %AppData%\npm\node_modules\business-stack on Windows). Use global install only if you are comfortable with that layout and upgrades overwriting the same tree.

Default URLs

| Service | URL | |---------|-----| | Web (Next) | http://127.0.0.1:3000 | | Gateway | http://127.0.0.1:3001 | | FastAPI | http://127.0.0.1:8000 |

setup uses these by default; interactive business-stack setup (without --yes) prompts for URLs.

Security note

Secrets in stack_secrets and generated .env files are plaintext at rest, like a normal .env. Protect the install directory and do not commit gateway/.env, frontend/web/.env.local, backend/.env, or *.sqlite.

License

See package.json (license field).