Documentation

BaseForge documentation

Practical guidance for using the website builder, setting up the generated app, and understanding the web stack BaseForge creates.

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. These docs are organized around the website builder flow and the generated web app that developers work with after download.

Read the page in order when evaluating a new generated app: choose options in the builder, confirm the supported stack, set up the downloaded project, then review feature-specific work before deployment.

Web Builder Guide

Start here to understand how the web builder turns project selections into a downloadable web app.

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.

Before downloading

Confirm the package manager matches how you want to install and run the downloaded app.
Use the preview step to check dependencies, scripts, env vars, and generated files before downloading.
If Prisma or Docker is disabled, go back and select PostgreSQL first.
Treat Auth.js credentials as a scaffold choice, not a complete login system.

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 App Setup

The downloaded zip is a normal Next.js project. Set it up outside BaseForge, install dependencies locally, and run checks inside the generated app directory.

Prepare the project folder: Unzip the download, enter the generated directory, and keep the generated files together before installing dependencies.
Install dependencies: Run the install command for the package manager selected in the builder. Do not mix npm and pnpm lockfiles in the same generated app.
Configure runtime values: Copy `.env.example` to `.env.local` when the selected features need environment variables, then replace placeholders before running feature code.
Run local checks: Start the dev server for manual QA, then run typecheck and build before treating the generated app as deployable.

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.

unzip my-app.zip
cd my-app
pnpm install
pnpm dev
pnpm typecheck
pnpm build

Feature Guides

Each optional feature changes the generated files, dependencies, environment variables, and setup work in the downloaded app.

shadcn/ui

Use this when the generated app should start with shadcn-compatible component conventions.

Adds shadcn-compatible files and a starter button component.
Depends on Tailwind CSS, which is fixed on in the MVP.
After download, keep generated UI primitives in `components/ui/` and place product-specific components outside that folder.
Use `lib/utils.ts` for shared class-name helpers instead of duplicating class merge logic.

Use the generated button component

import { Button } from "@/components/ui/button";

export function SaveButton() {
  return <Button type="submit">Save changes</Button>;
}

PostgreSQL

Use this when the app needs a PostgreSQL connection string and database-ready configuration.

Adds `DATABASE_URL` to `.env.example`.
Does not create or host a database.
For local development, point `DATABASE_URL` at your own PostgreSQL instance or the generated Docker Compose service when Docker is selected.
For production, provide a managed database connection string through your hosting provider's environment variable system.

Local PostgreSQL connection string

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/my_app"

Prisma

Use this when the generated app should include a typed database schema and Prisma Client workflow.

Requires PostgreSQL.
Adds Prisma schema, `prisma.config.ts`, and a database client helper.
The starter schema includes a minimal `User` model so the project has a real Prisma shape without pretending to model your product.
Edit `prisma/schema.prisma` before pushing schema changes to any shared database.
Use the generated database helper from `lib/db.ts` instead of creating Prisma clients in route handlers or components.

Add a model before pushing schema changes

model Post {
  id        String   @id @default(cuid())
  title     String
  body      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Use the generated Prisma helper

import { db } from "@/lib/db";

export async function listUsers() {
  return db.user.findMany({
    orderBy: { createdAt: "desc" },
  });
}

Auth.js credentials

Use this when the app needs the file structure for credentials auth, with real auth logic added by the developer.

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.
When combined with Prisma, connect the authorize function to your user table instead of leaving it as a null-returning placeholder.

Replace the generated authorize placeholder

async authorize(credentials) {
  if (!credentials?.email || !credentials.password) {
    return null;
  }

  const user = await findUserByEmail(credentials.email);
  if (!user) {
    return null;
  }

  const passwordIsValid = await verifyPassword(
    credentials.password,
    user.passwordHash,
  );

  if (!passwordIsValid) {
    return null;
  }

  return {
    id: user.id,
    email: user.email,
  };
}

Docker PostgreSQL

Use this when the generated app should include a local PostgreSQL service for development.

Adds `docker-compose.yml` for local development only.
Requires PostgreSQL selection.
Start the database before running Prisma commands or booting app code that reads from PostgreSQL.
Do not treat the local Docker service as production infrastructure; production database hosting must be configured separately.

Start and stop the local database

docker compose up -d
docker compose down

Generated Files

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

Core files to edit first

app/layout.tsx: Owns the root HTML shell, app metadata, and shared layout wrapper.
app/page.tsx: Starts as the editable home page for the generated product.
app/globals.css: Holds global styles and Tailwind imports for the generated app.
package.json: Defines generated dependencies and scripts for development, checks, and production builds.
.env.example: Documents required environment variables when selected features need runtime configuration.

shadcn/ui

Component-system starter files.

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

PostgreSQL

Database connection placeholder.

DATABASE_URL in .env.example

Prisma

Typed database schema and client helper.

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

Auth.js credentials

Credentials auth route and shared Auth.js options.

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

Docker PostgreSQL

Local development database service.

docker-compose.yml

Environment Variables

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

BaseForge only documents the variables needed by selected features. The generated app reads real values from your local `.env.local` file or from the environment configured by your deployment platform.

DATABASE_URL: Appears when PostgreSQL is selected. Use a local or managed PostgreSQL connection string; BaseForge does not create the database.
AUTH_SECRET: Appears when Auth.js credentials is selected. Replace the placeholder with a strong secret before testing auth flows.

`.env.local` examples

PostgreSQL only

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/my_app"

PostgreSQL plus Auth.js credentials

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/my_app"
AUTH_SECRET="replace-with-a-long-random-secret"

Scripts and Checks

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

Use `dev` while editing UI, routes, and feature wiring.
Use `typecheck` after changing TypeScript, Prisma helpers, Auth.js logic, or shared utilities.
Use `build` before deployment because it catches errors that may not show during local development.
Run Prisma scripts only when Prisma is selected and `DATABASE_URL` points at the intended development database.

dev: Run the Next.js development server while editing the generated app.
build: Build the generated Next.js app and catch production build issues.
start: Start the already-built app after `build` succeeds.
typecheck: Run TypeScript without emitting files before shipping changes.
db:generate: Optional Prisma script for generating Prisma Client after schema edits.
db:push: Optional Prisma script for syncing the schema to a development database after confirming `DATABASE_URL`.
db:studio: Optional Prisma script for inspecting local data in Prisma Studio.

Command workflows

Basic generated app checks

npm run dev
npm run typecheck
npm run build

Prisma local database workflow

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

Docker PostgreSQL plus Prisma

docker compose up -d
npm run db:generate
npm run db:push

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.

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.

Deployment Notes

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.

Production environment example

DATABASE_URL="postgresql://user:password@host:5432/production_db"
AUTH_SECRET="set-this-in-your-hosting-provider"

Run typecheck and build in the generated app before connecting it to hosting.
Set production environment variables in the hosting provider, not only in `.env.local`.
Use a real PostgreSQL provider for production when database features are selected.
Replace Auth.js placeholder logic with real user lookup, password hashing, and verification before enabling sign-in.
Review generated README notes for selected features before handing the app to another developer.

Limitations

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.