Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cubby.pro/llms.txt

Use this file to discover all available pages before exploring further.

​
cubby init

Scaffold a new Cubby app with Next.js and Prisma preconfigured for the platform (SQLite by default; Neon Postgres on Builder/Pro).

​
Usage

cubby init [name]

​
Arguments

ArgumentDescriptionDefault
nameApp name or . for current directorymy-cubby-app

​
Examples

# Create app in new directory
cubby init myapp

# Initialize in current directory
cubby init .

# Create with default name
cubby init

​
What Gets Created

The scaffold includes a complete Next.js 16 + Prisma setup (SQLite by default): 
myapp/
├── app/
│   ├── api/
│   │   └── health/
│   │       └── route.ts       # Health check endpoint
│   ├── page.tsx               # Home page
│   ├── layout.tsx             # Root layout
│   └── globals.css            # Global styles
├── lib/
│   └── db.ts                  # Prisma client singleton
├── prisma/
│   └── schema.prisma          # Database schema
├── public/
│   ├── manifest.json          # PWA manifest
│   └── favicon.ico
├── .env.example               # Environment template
├── .gitignore
├── cubby.yaml                 # Platform configuration
├── CUBBY.md                   # AI context file
├── next.config.ts             # Next.js config (standalone output)
├── package.json
└── tsconfig.json

​
App Name Rules

App names must be DNS-safe:
  • 3-30 characters
  • Lowercase letters, numbers, and hyphens only
  • Must start and end with a letter or number
Names are automatically slugified:
  • My App becomes my-app
  • app_name becomes app-name

​
After Initialization

cd myapp
npm install
npm run dev
For the default SQLite template, npm run dev needs no Docker and no local database — Cubby runs prisma db push for you on deploy. Hot reload works immediately. If you chose the Neon Postgres template, use cubby dev instead — it runs a local Postgres container and requires Docker (see cubby dev). 
cubby dev   # Neon template — Docker required; local Postgres + automatic schema sync

​
The CUBBY.md File

Every scaffolded app includes a CUBBY.md file that provides context for AI coding assistants. It documents:
  • Platform constraints
  • API route patterns
  • Database access patterns
  • Authentication (handled by Cubby SSO)
  • What NOT to do
When using Claude or other AI tools, this file helps them understand Cubby’s conventions.

​
Customizing the Schema

Edit prisma/schema.prisma to define your data models: 
model Task {
  id        String   @id @default(cuid())
  title     String
  completed Boolean  @default(false)
  createdAt DateTime @default(now())
}
You only need to push the schema locally if you want a live local database. On the SQLite template, the data/ dir must exist first, or prisma db push fails with P1003 Database does not exist: 
mkdir -p data              # create the data/ dir (prisma db push then creates the .db file)
npx prisma db push
npx prisma generate
On deploy, Cubby runs prisma db push for you — so for frontend work you can just run npm run dev. On the Neon template, cubby dev (Docker) handles schema sync automatically.

​
Next Steps

After cubby init:
  1. Install dependencies: npm install
  2. Start development: npm run dev (SQLite/no-DB; no Docker) or cubby dev (Neon; Docker)
  3. Edit your schema: prisma/schema.prisma
  4. Build your app: Add pages in app/
  5. Deploy: cubby deploy