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

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

Quick Start

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

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

Docs

• AGENTS.md — Architecture, conventions, and anti-patterns for AI agents
• DEVELOPMENT.md — Local setup, Coolify deployment, troubleshooting

Environments

• Dev: develop branch
• Prod: main branch

License

MIT — do whatever you want.