create-zero-stack

Scaffold production-ready, zero-cost stack applications in seconds.

Quick Start

npx @siddmo/create-zero-stack my-app
cd my-app
pnpm dev

The CLI guides you through everything else.

What You Get

| Component | Technology | Free Tier | |-----------|------------|-----------| | Infrastructure | SST v3 | Deploys to AWS | | API | FastAPI + Lambda | 1M requests/mo | | Database | Supabase Postgres | 500MB | | Auth | Supabase Auth | 50k MAUs | | Storage | Cloudflare R2 | 10GB (optional) | | Web | React + Vite | Optional | | Mobile | Expo | Optional | | Payments | Stripe + RevenueCat | Optional | | Notifications | Novu | Optional |

Prerequisites

Required

• Node.js >= 18
• pnpm (npm install -g pnpm)
• AWS Account with credentials configured
• Supabase Account (free at supabase.com)

Optional

• Cloudflare Account - for R2 storage (can skip during setup)
• GitHub CLI - for automatic repo creation and secrets
• Custom Domain - managed by Cloudflare DNS

Setup Flow

When you run the CLI, it:

1. Detects your existing AWS, Supabase, and Cloudflare configurations
2. Authenticates via browser OAuth for missing services
3. Creates Supabase project and R2 bucket automatically
4. Generates all required API credentials
5. Pushes secrets to GitHub for CI/CD
6. Scaffolds a complete monorepo ready to deploy

Checking your environment...

  AWS          ✓ Configured (us-east-1)
  Supabase     ✓ Authenticated
  Cloudflare   ○ Not configured
  GitHub       ✓ Authenticated as @username

? Set up missing services and create project? Yes

Setting up services...

✓ Supabase project: my-app (us-east-1)
○ Cloudflare R2 not configured. File storage will need manual setup.

? Configure custom domain for production? No
  Using auto-generated URLs for all environments.

✓ Setup complete!

Configuration Options

Cloudflare R2 (Optional)

R2 provides S3-compatible storage with zero egress fees. You can:

• Set it up during CLI flow - the CLI will create a bucket and generate credentials
• Skip it - configure manually later or use a different storage solution
• Enable R2 first at dash.cloudflare.com if you want automated setup

Custom Domain (Optional)

By default, your app uses auto-generated AWS URLs:

• API: https://<id>.lambda-url.<region>.on.aws
• Web: https://<id>.cloudfront.net

For production custom domains (e.g., api.example.com):

1. Manage your domain with Cloudflare DNS
2. Answer "Yes" to "Configure custom domain for production?"
3. Create a Cloudflare API token with "Edit zone DNS" permission
4. Add the token to GitHub secrets: CLOUDFLARE_API_TOKEN

Project Structure

my-app/
├── sst.config.ts          # SST infrastructure config
├── infra/                  # Infrastructure definitions
│   ├── api.ts             # Lambda API
│   ├── storage.ts         # R2 bucket
│   ├── web.ts             # Static site
│   └── dns.ts             # Domain config
├── apps/
│   ├── api/               # FastAPI backend
│   ├── web/               # React + Vite (optional)
│   └── mobile/            # Expo app (optional)
├── packages/
│   ├── core/              # Shared types & utils
│   └── supabase/          # Database client
└── .github/workflows/     # CI/CD pipeline

Commands

# Development
pnpm dev                   # Start SST dev server

# Deployment
pnpm deploy:dev            # Deploy to dev stage
pnpm deploy:production     # Deploy to production

# Cleanup
pnpm remove:dev            # Remove dev resources
pnpm remove:production     # Remove production resources

# Build & Test
pnpm build                 # Build all packages
pnpm lint                  # Run linting
pnpm test                  # Run tests

Deployment

Branch-Based CI/CD

The generated project includes GitHub Actions for automatic deployment:

| Branch | Stage | Trigger | |--------|-------|---------| | develop | dev | Push | | main | production | Push |

Environment Variables

All credentials are stored in .env (local) and GitHub Secrets (CI/CD):

# Supabase (same project for all environments)
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...

# AWS
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

# Cloudflare R2 (if configured)
CLOUDFLARE_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=...

CLI Options

# Interactive (default)
npx @siddmo/create-zero-stack my-app

# Skip automated setup
npx @siddmo/create-zero-stack my-app --skip-setup

# CI mode (non-interactive)
npx @siddmo/create-zero-stack my-app --CI --web --payments

# All flags
--skip-setup        Skip service setup, configure manually
--noGit             Skip git initialization
--noInstall         Skip dependency installation
-y, --default       Use default options
--CI                Non-interactive mode
--web               Include React + Vite frontend
--mobile            Include Expo app
--payments          Include Stripe + RevenueCat
--notifications     Include Novu
--domain <domain>   Set production domain
--no-domain         Skip domain configuration

Manual Setup

If you skip automated setup or need to configure services manually:

AWS

aws configure
# Or set environment variables:
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

Supabase

1. Create project at supabase.com
2. Go to Settings > API
3. Copy URL, anon key, and service_role key

Cloudflare R2

1. Enable R2 at dash.cloudflare.com
2. Create a bucket
3. Create API token at R2 > Manage R2 API Tokens
4. Copy Access Key ID and Secret Access Key

GitHub Secrets

gh secret set AWS_ACCESS_KEY_ID --body "..."
gh secret set AWS_SECRET_ACCESS_KEY --body "..."
gh secret set SUPABASE_URL --body "..."
gh secret set SUPABASE_ANON_KEY --body "..."
gh secret set SUPABASE_SERVICE_ROLE_KEY --body "..."
# Add R2 secrets if configured

Troubleshooting

Permission Denied Errors

If you accidentally ran commands with sudo, fix permissions:

sudo chown -R $(whoami):staff ~/.bun ~/.cache ~/Library/Application\ Support/sst

SST Dev Fails

Check the log:

cat .sst/log/sst.log

Or run with verbose output:

pnpm sst dev --print-logs

Missing Environment Variables

Ensure .env exists and has all required values:

cp .env.example .env
# Edit .env with your credentials

Architecture

Why This Stack?

• Lambda + FastAPI: Zero cost at rest, instant scaling, Python ecosystem
• Supabase: Managed Postgres with auth, realtime, and edge functions
• Cloudflare R2: S3-compatible with zero egress fees
• SST v3: Infrastructure-as-code with great DX

Single Supabase Project

The CLI creates one Supabase project used by all environments (dev, production). This simplifies setup and reduces costs. Data isolation is handled at the application level via SST stages.

License

MIT

Built with the Zero-Cost Stack philosophy: production-ready apps with minimal fixed costs.