Documentation

BaseForge documentation

Practical notes for the website builder, generated project output, supported stack options, and the published CLI package that reuses the same shared generator core.

Open Builder

Overview

BaseForge is a TypeScript-first developer project generator. The MVP is website-first: users choose options, preview generated output, and download a zip.

The generated project is intended to be unzipped and edited locally. The shared generator core is also used by the published `@baseforge/create` CLI package.

Quick Start

1Open the builder.
2Enter a project name.
3Choose supported options.
4Preview the generated output.
5Download the zip.
6Unzip the project locally.
7Install dependencies.
8Start development.

unzip my-app.zip
cd my-app
npm install
npm run dev
npm run typecheck
npm run build

pnpm variant

The generated project supports pnpm guidance when pnpm is selected in the builder.

pnpm install
pnpm dev

Website Builder Flow

Project: Project name and package manager.
Framework: Fixed MVP foundation: Next.js, TypeScript, App Router, and no `src/` folder.
Styling and UI: Tailwind CSS is fixed on. shadcn/ui is optional.
Database: Choose no database setup or PostgreSQL.
ORM: Choose no ORM or Prisma. Prisma requires PostgreSQL.
Auth: Choose no auth or the Auth.js credentials scaffold.
Extras: Optional PostgreSQL Docker Compose plus always-generated README and `.env.example`.
Preview: Review stack, dependencies, env vars, scripts, and generated file tree.
Download: Generate and download the project zip.

Supported Stack

These are the exact MVP option groups exposed by `@baseforge/schema`. Unsupported frameworks, languages, routers, databases, ORMs, auth providers, and package managers are not documented as available.

Category	Supported options	Notes
Framework	Next.js	MVP-supported.
Language	TypeScript	MVP-supported.
Router	App Router	MVP-supported.
Project structure	No src folder	MVP-supported.
Styling	Tailwind CSS	MVP-supported.
UI	None shadcn/ui	MVP-supported.
Database	None PostgreSQL	MVP-supported.
ORM	None Prisma	MVP-supported.
Auth	None Auth.js credentials scaffold	Credentials scaffold only.
Docker	None PostgreSQL Docker Compose	Local PostgreSQL only.
Package manager	npm pnpm	MVP-supported.

Generated Project Structure

The generated project keeps `app/`, `components/`, and `lib/` at the project root. Generated projects do not use a `src/` directory.

app/
  layout.tsx
  page.tsx
  globals.css
components/
lib/
package.json
tsconfig.json
next.config.ts
postcss.config.mjs
.env.example
.gitignore
README.md

shadcn/ui

components.json
lib/utils.ts
components/ui/button.tsx

PostgreSQL

DATABASE_URL in .env.example

Prisma

prisma/schema.prisma
prisma.config.ts
lib/db.ts

Auth.js credentials

auth.ts
app/api/auth/[...nextauth]/route.ts
AUTH_SECRET in .env.example

Docker PostgreSQL

docker-compose.yml

Optional Features

shadcn/ui

Adds shadcn-compatible files and a starter button component.
Depends on Tailwind CSS, which is fixed on in the MVP.
Developers can extend the component set after downloading the project.

PostgreSQL

Adds `DATABASE_URL` to `.env.example`.
Does not create or host a database.
Production deployments need a real connection string supplied by the developer.

Prisma

Requires PostgreSQL.
Adds Prisma schema, `prisma.config.ts`, and a database client helper.
Use Prisma commands on a development database first, not blindly against production.

npm run db:generate
npm run db:push
npm run db:studio

Auth.js credentials

Adds an Auth.js credentials scaffold, not production-ready user management.
The generated authorize logic is a placeholder and real user lookup must be implemented.
Secure password hashing and verification must be added by the developer.
`AUTH_SECRET` must be replaced before using authentication.

Docker PostgreSQL

Adds `docker-compose.yml` for local development only.
Requires PostgreSQL selection.
Production database hosting must be configured separately.

docker compose up -d
docker compose down

Environment Variables

`.env.example` is only an example. Replace placeholder secrets and keep production values out of source control.

DATABASE_URL: Appears when PostgreSQL is selected.
AUTH_SECRET: Appears when Auth.js credentials is selected.

Scripts

Common scripts are generated for every project. Prisma scripts are added only when Prisma is selected.

dev: Run the Next.js development server.
build: Build the generated Next.js app.
start: Start the built app.
typecheck: Run TypeScript without emitting files.
db:generate: Optional Prisma script for generating Prisma Client.
db:push: Optional Prisma script for syncing the schema to a development database.
db:studio: Optional Prisma script for opening Prisma Studio.

Downloaded Project Usage

After download, unzip locally, install dependencies, copy `.env.example` to `.env.local` when selected features need env vars, configure values, and run checks before deployment.

cp .env.example .env.local
npm install
npm run dev
npm run typecheck
npm run build

The exact env setup depends on the selected optional features.

Compatibility Rules

Prisma requires PostgreSQL.
PostgreSQL Docker Compose is only available when PostgreSQL is selected.
Auth.js credentials can be generated without a database.
Auth.js credentials with Prisma requires the Prisma/PostgreSQL combination.
shadcn/ui requires Tailwind CSS. Because Tailwind is fixed in the MVP, shadcn/ui is normally compatible.

Limitations

The CLI package is published as @baseforge/create.
Only Next.js is supported.
Only TypeScript is supported.
Only App Router is supported.
Generated projects do not use `src/`.
Only Tailwind CSS is supported.
Only PostgreSQL is supported as a database option.
Only Prisma is supported as an ORM option.
Auth.js credentials is a scaffold, not complete production auth.
BaseForge does not host databases.
BaseForge does not install generated dependencies.
BaseForge does not run generated project code on the server.
BaseForge does not save project presets.
BaseForge does not provide user accounts in the MVP.

CLI Status

CLI generation is available through the published `@baseforge/create` package and uses the same shared generator core as the website.

npx @baseforge/create@latest

Troubleshooting

Invalid project name: Use lowercase letters, numbers, and hyphens only.
Prisma option is disabled: Select PostgreSQL first.
Docker PostgreSQL is disabled: Select PostgreSQL first.
Download failed: Check selected options and try again.
npm install fails: Check Node.js version and network access.
Build fails after download: Verify env vars and optional feature setup.
Auth does not work out of the box: Auth.js credentials output is a scaffold; implement real user lookup and password verification.