Skip to main content

​
CUBBY.md File

The CUBBY.md file is a markdown document that provides context for AI coding assistants. Every Cubby app includes this file in the project root.

​
Purpose

When using Claude, ChatGPT, or other AI tools to build your app, they need to understand:
  • Cubby’s platform constraints
  • How to write API routes correctly
  • Database access patterns
  • What to avoid (auth libraries, hardcoded values)
CUBBY.md provides all this context in a format AI tools can reference.

​
Location

The file lives in your project root: 
my-app/
├── CUBBY.md          # AI context file
├── cubby.yaml        # Platform config
├── package.json
└── ...

​
What’s Included

The default CUBBY.md created by cubby init covers:

​
Stack Information

## Stack

- Next.js 16 (App Router, Turbopack)
- Prisma ORM + PostgreSQL
- Docker container deployment

​
Project Structure

## Project Structure

app/
  api/           -- API routes (server-only)
  page.tsx       -- Pages (server components by default)
lib/
  db.ts          -- Prisma client singleton
prisma/
  schema.prisma  -- Database schema

​
CLI Commands

## CLI Commands

cubby dev          # Local development with hot reload
cubby deploy       # Build and deploy to production
cubby secrets set  # Manage environment variables

​
API Route Patterns

The file includes complete examples for:
  • Collection routes (GET all, POST create)
  • Dynamic routes with async params (Next.js 16 pattern)
  • Server components vs client components
  • Form handling with Server Actions

​
Platform Constraints

## Platform Constraints

### Environment Variables
- PORT -- Provided by runtime (default: 3000). Do not hardcode.
- DATABASE_URL -- Provisioned automatically. Never commit to repo.
- Use `cubby secrets` for production secrets, not .env files.

### Build Requirements
- next.config.ts must have output: "standalone" for Docker builds

​
Authentication

## Authentication

Cubby handles authentication via platform SSO. Your app does NOT need its own auth system.

- Users authenticate once through the Cubby platform
- Authenticated user identity is passed via request headers
- Do not install auth libraries (NextAuth, Clerk, etc.)

​
Forbidden Patterns

## Forbidden Patterns

- Do not use middleware.ts -- renamed to proxy.ts in Next.js 16
- Do not hardcode DATABASE_URL or commit .env files
- Do not install auth libraries -- Cubby SSO handles authentication
- Do not use prisma migrate dev in production

​
Customizing CUBBY.md

You can extend CUBBY.md with app-specific context: 
# My Todo App

A task management app with AI-powered suggestions.

## Custom Models

model Todo {
  id        String  @id
  title     String
  priority  Int     # 1 = high, 2 = medium, 3 = low
  userId    String  # Owner's Cubby user ID
}

## API Routes

- POST /api/todos - Create a new todo
- GET /api/todos - List user's todos
- PUT /api/todos/[id] - Update a todo
- DELETE /api/todos/[id] - Delete a todo

## Business Logic

- Users can only see their own todos (filter by userId)
- High priority todos appear first
- Completed todos move to bottom of list

​
How AI Uses CUBBY.md

When you ask Claude or another AI to help with your app, the AI should:
  1. Read CUBBY.md at the start of the conversation
  2. Follow the patterns documented there
  3. Avoid forbidden patterns
  4. Use the correct API route signatures
If your AI isn’t following Cubby conventions, remind it to read CUBBY.md for context.

​
Full Template

View the complete default CUBBY.md in the GitHub repository or run cubby init to see it in your project.