npm package: @siddmo/create-zero-stack
Description: CLI to scaffold production-ready zero-cost stack applications
Latest version: 0.2.9

# create-zero-stack

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

## Quick Start

```bash
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](https://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](https://dash.cloudflare.com/?to=/:account/r2) 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

```bash
# 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):

```env
# 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

```bash
# 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

```bash
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](https://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](https://dash.cloudflare.com/?to=/:account/r2)
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

```bash
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:

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

### SST Dev Fails

Check the log:

```bash
cat .sst/log/sst.log
```

Or run with verbose output:

```bash
pnpm sst dev --print-logs
```

### Missing Environment Variables

Ensure `.env` exists and has all required values:

```bash
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.