create-mococa-app

A template generator for creating Mococa-style monorepo projects with Nullstack, Biome, and Tailwind CSS.

Usage

With npx (npm)

npx create-mococa-app

With bunx (Bun)

bunx create-mococa-app

With npm

npm create mococa-app

Usage

npx create-mococa-app [project-name] [flags]

Arguments:

• [project-name] - Optional. Name of your project (e.g., my-app, my-cool-project)

Flags:

• --help or -h - Show help message
• --current or -c - Create project in current directory
• --domain <domain> - Specify custom domain (default: {project-name}.com)
• --skip - Skip all prompts and use default values (can be combined with other flags)
• --full - Skip prompts and include all features
• --except <feature> or -e <feature> - Exclude features when using --full (can be used multiple times)
  • Valid features: api, cognito, lambda, dynamo, s3, environments
• --api - Include Elysia API server (Bun-based)
• --cognito - Include AWS Cognito authentication
• --lambda - Include AWS Lambda + API Gateway infrastructure
• --dynamo - Include DynamoDB infrastructure
• --s3 - Include S3 storage bucket infrastructure
• --environments - Configure multiple environments (prompts for environment names)

Examples

# Interactive prompts (default)
npx create-mococa-app

# Quick start with project name
npx create-mococa-app my-cool-app

# Create in current directory
npx create-mococa-app my-app --current

# Create in current directory (short flag)
npx create-mococa-app my-app -c

# With custom domain
npx create-mococa-app my-app --domain example.com

# Minimal project (no optional features, no prompts)
npx create-mococa-app my-app --skip

# Skip prompts but include specific features
npx create-mococa-app my-app --skip --cognito

# Full setup with all features (no prompts)
npx create-mococa-app my-app --full

# Full setup except specific features
npx create-mococa-app my-app --full --except=s3 --except=dynamo

# Full setup except specific features (short flag)
npx create-mococa-app my-app --full -e s3 -e dynamo

# With Elysia API server
npx create-mococa-app my-app --api

# With Elysia API + Cognito authentication
npx create-mococa-app my-app --api --cognito

# With Lambda support
npx create-mococa-app my-app --lambda

# With DynamoDB support
npx create-mococa-app my-app --dynamo

# With S3 storage support
npx create-mococa-app my-app --s3

# With custom environments (prompts for input)
npx create-mococa-app my-app --environments

# Combine multiple flags
npx create-mococa-app my-project --api --cognito --lambda --dynamo --s3 --environments

# Full setup in current directory
npx create-mococa-app my-project -c --api --cognito --lambda --dynamo --s3 --environments

Note: Without --environments, only a production environment is created by default.

Features

• ✨ Bun workspaces monorepo structure
• 🎯 Nullstack framework for full-stack development
• 🎨 Tailwind CSS for styling
• 🔧 Biome for fast formatting and linting
• 📦 Shared UI components package
• 🚀 Pre-configured build scripts
• 📝 TypeScript configuration
• 🔐 Optional Elysia API server with OAuth + Cognito support
• ☁️ Optional AWS infrastructure (Lambda, DynamoDB, S3, Cognito)
• 🏗️ Pulumi IaC with component-based architecture

What's Included

your-app/
├── apps/
│   ├── landing-page/          # Nullstack app with Tailwind CSS
│   │   ├── src/
│   │   │   ├── Application.jsx
│   │   │   └── Home.jsx
│   │   ├── client.js
│   │   ├── server.js
│   │   ├── webpack.config.js
│   │   ├── tailwind.config.js
│   │   └── package.json
│   └── api/                   # Elysia API server (with --api)
│       ├── src/
│       │   ├── handlers/      # Route handlers (public, private, admin)
│       │   ├── services/      # Business logic & integrations
│       │   └── main.ts
│       └── package.json
├── packages/
│   ├── ui/                    # Shared UI components
│   │   ├── src/
│   │   └── package.json
│   ├── constants/             # Project constants & environment config
│   │   ├── src/index.ts
│   │   └── package.json
│   └── lambdas/               # Lambda functions (with --lambda)
│       ├── src/
│       ├── build.js
│       └── package.json
├── infrastructure/            # Pulumi IaC
│   ├── src/
│   │   ├── components/        # High-level infrastructure components
│   │   │   └── backend.ts     # Backend component (Cognito, DynamoDB, S3, API Gateway)
│   │   ├── resources/         # Individual AWS resources
│   │   │   ├── certificate.ts
│   │   │   ├── cognito.ts     # (with --cognito)
│   │   │   ├── dns.ts
│   │   │   ├── dynamo.ts      # (with --dynamo)
│   │   │   ├── s3-storage.ts  # (with --s3)
│   │   │   ├── s3-website.ts
│   │   │   ├── apigateway.ts  # (with --lambda)
│   │   │   └── lambdas/       # (with --lambda)
│   │   └── index.ts
│   ├── Pulumi.yaml
│   └── package.json
├── biome.json                 # Biome configuration
├── package.json               # Root package with workspaces
└── README.md

After Creation

1. Navigate to your project:

   cd your-app

2. Install dependencies:

   bun install

3. Start the development server:

   bun start

4. Open http://localhost:3000 in your browser

If you included Elysia API (--api)

Your project includes:

• apps/api/ - Elysia API server with TypeScript
• Route handlers organized by access level (public, private, admin)
• OAuth support (Google, GitHub) via bun-mococa
• Session management with in-memory storage
• CORS configured for your domains via constants
• Optional Cognito integration (with --cognito)

Start the API server:

cd apps/api
bun run dev

If you included Cognito (--cognito)

Your project includes:

• Cognito User Pool with email/password authentication
• Custom attributes: full_name, phone, profile_picture, provider
• Email verification required
• Password policy enforced
• Cognito endpoints in Elysia API:
  • POST /auth/login - Login with email/password
  • POST /auth/register - Register new user
  • POST /auth/confirm-email - Confirm email with code
  • POST /auth/resend-confirmation-code - Resend verification
  • POST /auth/forgot-password - Initiate password reset
  • POST /auth/reset-password - Complete password reset

Note: Without --cognito, these endpoints are removed from the API.

If you included Lambda (--lambda)

Your project includes:

• packages/lambdas/ - Lambda functions with example GET/POST handlers
• API Gateway infrastructure with Lambda integrations
• Example endpoints at /example (GET and POST)

To use DynamoDB with your Lambdas, pass the dynamodb prop to ApiLambdas in infrastructure/src/resources/lambdas/index.ts and update your Lambda functions to interact with the table.

If you included DynamoDB (--dynamo)

Your project includes:

• DynamoDB table resource in infrastructure/src/resources/dynamo.ts
• Table configured with pk and sk keys (single-table design)
• TTL enabled on timetolive attribute
• Deletion protection for production environment

The DynamoDB resource is created but not automatically connected to Lambdas. To use it:

1. Pass dynamodb to your Lambda resources
2. Add DynamoDB permissions to your Lambda IAM role
3. Pass the table name as an environment variable to your Lambda functions

If you included S3 Storage (--s3)

Your project includes:

• S3 storage bucket resource in infrastructure/src/resources/s3-storage.ts
• Bucket naming via constants: {projectName}-storage-{environment}
• Versioning enabled for all environments
• Private bucket with blocked public access
• CORS configuration for web uploads

The bucket name is managed in packages/constants/src/index.ts via S3_STORAGE_BUCKETS.

Infrastructure Architecture

Backend Component

All AWS backend resources are organized in a single BackendComponent (infrastructure/src/components/backend.ts):

backend.cognito      // CognitoResource (with --cognito)
backend.dynamo       // DynamoResource (with --dynamo)
backend.storage      // S3StorageResource (with --s3)
backend.apigateway   // ApigatewayResource + Lambdas (with --lambda)

This component-based approach:

• Groups related resources together
• Simplifies dependency management
• Makes infrastructure more maintainable
• Enables conditional resource creation via CLI flags

Constants Package

All projects include a packages/constants/ package with:

• Project name and base domain
• Environment configuration (customizable with --environments)
• Domain names per app per environment
  • landing-page: {env}.{domain} (production uses root domain)
  • api: api-{env}.{domain} (production uses api.{domain})
  • apigw: apigw-{env}.{domain} (production uses apigw.{domain})
• DynamoDB table names per environment
• S3 bucket names per environment
• Cognito User Pool names per environment

Use it across your infrastructure and application code for consistent naming.

Default Environments

• Without --environments: Only production environment
• With --environments: You'll be prompted to enter comma-separated environment names (e.g., development,staging,production)

Available Scripts

• bun start - Start the development server
• bun run build - Build for production
• bun run fmt - Format code with Biome

Development & Testing

To test this generator locally before publishing to npm:

# From any directory, run the local generator
bunx /path/to/create-mococa-app

# Test with project name and current directory
bunx /path/to/create-mococa-app my-test-app --current

# Test in a specific location
cd /tmp
bunx /path/to/create-mococa-app my-test-app --api --cognito

# Test with all features
bunx /path/to/create-mococa-app test-app --api --cognito --lambda --dynamo --s3 --environments

License

MIT