t-convex-nextjs-saas/README.md

# convex-next-saas

A personal, opinionated SaaS template built for speed. Next.js 16 + Convex self-hosted + Better Auth + Resend.

> This template is tailored for self-hosted Convex on Coolify with a private Forgejo workflow. It's not trying to be a generic marketplace template — it's the setup I actually use to ship projects fast.

## Stack

- **Frontend**: Next.js 16 (App Router), React 19, TypeScript 5, Tailwind CSS 4
- **Backend**: Convex self-hosted (Docker on Coolify)
- **Auth**: Better Auth (email/password, email verification, password reset)
- **Email**: Resend (free tier: 3,000 emails/month)
- **UI**: shadcn/ui (radix-nova), @hugeicons/react
- **i18n**: next-intl v4 with locale routing (`/en`, `/pl`)
- **State**: RSC + Client Components hybrid
- **Validation**: Zod v4
- **Linting**: ESLint + oxlint

## What's Included

- [x] Email/password auth with HIBP password checking
- [x] Email verification flow
- [x] Forgot / reset password flow
- [x] Change password (authenticated)
- [x] Locale-based routing (EN / PL)
- [x] Theme switching (dark/light/system)
- [x] Protected routes with redirect + callbackURL
- [x] Runtime env validation (Zod)
- [x] GitHub Actions CI (lint + build)
- [x] Project init script (`bin/init-template.mjs`)
- [x] PWA Lite installability (manifest + icons)
- [x] Docker deployment (Dockerfile + docker-compose)

## Quick Start

```bash
git clone <your-forgejo-repo> my-project
cd my-project
pnpm install

# Copy and fill env vars
cp .env.example .env.local

# Set up Convex backend (see DEVELOPMENT.md)
# Then:
pnpm dev --webpack
```

> ⚠️ **Always use `--webpack`** — Turbopack is broken in Next.js 16.2.1 (900% CPU spike).

## Project Bootstrap

```bash
node bin/init-template.mjs my-project
cd my-project
# Fill .env.local, deploy Convex, done.
```

## Docs

- [`AGENTS.md`](./AGENTS.md) — Architecture, conventions, and anti-patterns for AI agents
- [`DEVELOPMENT.md`](./DEVELOPMENT.md) — Local setup, Coolify deployment, troubleshooting

## Environments

- **Dev**: `develop` branch
- **Prod**: `main` branch

## License

MIT — do whatever you want.