nxtkofi
4ae60473b6
Rewrite README.md as a clean template landing page. Update DEVELOPMENT.md with Resend setup instructions and expanded checklist. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
69 lines
2 KiB
Markdown
69 lines
2 KiB
Markdown
# 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`)
|
|
|
|
## 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.
|