Create a New App

Create a new web application in the monorepo using the /create-new-app skill.

Overview

The monorepo includes a ready-to-use web app template at templates/web/. Instead of manually copying files and editing configs, you can use the /create-new-app skill in Claude Code to scaffold everything in one go.

The template includes:

  • Next.js 15 with App Router and TypeScript (strict mode)
  • Tailwind CSS for styling
  • Auth middleware pre-configured for the shared authentication service
  • Database helper (pg library) with connection pooling
  • AI documentation structure (CLAUDE.md, PLAN.md, ai_docs/)
  • Deployment config patterns for Railway + GitHub Actions

The /create-new-app Skill

The /create-new-app skill automates the entire app creation process. It handles template copying, configuration, deployment setup, and documentation — all from a single command.

How to Use It

In Claude Code, type:

Invoke the skilltext
/create-new-app <app-name>

That's it. Claude will ask you for any missing details and handle everything else.

What You'll Be Asked

Claude needs four things to create your app:

  1. App name — kebab-case (e.g. meal-planner, task-board)
  2. What the app does — a short description
  3. Key features — list the main capabilities
  4. Target users — who will use this app

If you provide the app name via the command (e.g. /create-new-app meal-planner), Claude will use that name and only ask for anything else that's missing.

Example: provide everything upfront
Claude prompt
/create-new-app meal-planner This app helps a shared kitchen plan weekly meals. Key features: browse recipes, create weekly meal plans, generate shopping lists. Target users: members of a co-working kitchen.

If you provide all the details in one message, Claude will proceed without asking follow-up questions.

What the Skill Does

Behind the scenes, /create-new-app runs through these phases automatically:

Phase 1: Scaffold from Template

StepWhat Happens
Copy templatetemplates/web/ is copied to apps/<app-name>/
Update package namepackage.json name is set to your app name
Update metadataapp/layout.tsx gets your app title and description
Add root scriptsdev:<app-name>, build:<app-name>, start:<app-name> added to root package.json
Install dependenciespnpm install runs from the monorepo root

Phase 2: Customize AI Documentation

Claude replaces all template placeholders in CLAUDE.md, PLAN.md, and ai_docs/:

PlaceholderReplaced WithExample
[app-name]kebab-case namemeal-planner
[app_name]snake_case (table prefix)meal_planner
[App Name]Title caseMeal Planner

If you provided a description, features, and target users, Claude also fills in ai_docs/00_product_brief.md. The remaining docs (01–06) can be filled as you build.

Phase 3: Set Up Deployment

Claude creates three files following existing app patterns:

  • apps/<app-name>/deploy.config.yml — service ID and root directory
  • .github/workflows/deploy-app-<app-name>-staging.yml — manual deploy to staging
  • .github/workflows/deploy-app-<app-name>-production.yml — auto-deploy on merge to main

Phase 4: Environment and Local Dev

Claude creates .env from .env.example and tells you which variables need real values. Then you can start the dev server:

Start the dev server (from monorepo root)bash
pnpm dev:meal-planner

After Scaffolding: Start Building

With the app created, you can start implementing features.

Begin development
Claude prompt
meal-planner: I want to start working on this app. Please read CLAUDE.md and PLAN.md, then begin Phase 1 implementation. Follow the monorepo workflow: create a feature branch from main, implement, test build, then create a PR.

For ongoing development, follow these workflow guides:

Template Directory Structure

What the template includestext
apps/my-app-name/
├── package.json              # Dependencies (name updated)
├── tsconfig.json             # TypeScript strict mode
├── next.config.ts            # Next.js configuration
├── tailwind.config.ts        # Tailwind CSS
├── postcss.config.js         # PostCSS
├── middleware.ts             # Auth middleware (pre-configured)
├── deploy.config.yml         # Deployment config (created by skill)
├── CLAUDE.md                 # AI development guardrails
├── PLAN.md                   # Project status tracking
├── README.md                 # App documentation
├── app/
│   ├── layout.tsx            # Root layout (metadata updated)
│   ├── page.tsx              # Home page (starter)
│   ├── globals.css           # Global styles
│   └── _lib/
│       └── db.ts             # Database connection pool
└── ai_docs/
  ├── README.md             # Documentation index
  ├── 00_product_brief.md   # Product definition
  ├── 01_user_experience.md # UI/UX flows
  ├── 02_architecture.md    # Technical architecture
  ├── 03_data_contract.md   # Data & API contracts
  ├── 04_integrations.md    # External services
  ├── 05_runbook.md         # Operations
  ├── 06_acceptance_tests.md# Test scenarios
  └── plans/
      └── README.md         # Phase plans index

Manual Fallback

If you prefer to scaffold manually without the skill:

Manual stepsbash
# Copy the template
cp -r templates/web/ apps/my-app-name/

# Edit apps/my-app-name/package.json — set "name": "my-app-name"
# Edit apps/my-app-name/app/layout.tsx — set title and description

# Add scripts to root package.json:
# "dev:my-app-name": "pnpm --filter my-app-name dev"
# "build:my-app-name": "pnpm --filter my-app-name build"
# "start:my-app-name": "pnpm --filter my-app-name start"

# Install dependencies (MUST run from monorepo root)
pnpm install

# Create deployment config and workflow files
# (see .github/workflows/deploy-app-checkin-board-*.yml for patterns)

Quiz

Quiz

What is the fastest way to create a new app in the monorepo?