Kosuke Template

A modern Next.js 16 template with TypeScript, Better Auth authentication with Organizations, Stripe Billing, DigitalOcean Spaces, PostgreSQL database, Shadcn UI, Tailwind CSS, and Sentry error monitoring. Built for multi-tenant SaaS applications.

Production-ready Next.js 16 SaaS starter with Better Auth Organizations, Stripe Billing, and complete multi-tenant functionality.

• Next.js 16 with App Router
• TypeScript for type safety
• Better Auth Authentication for user management with Organizations
• PostgreSQL database with Drizzle ORM
• Shadcn UI components with Tailwind CSS
• Stripe billing integration with automated sync (personal & organization subscriptions)
• BullMQ + Redis for background jobs and scheduled tasks
• Resend email service with React Email templates
• Profile image uploads with DigitalOcean Spaces or S3-like storage
• Multi-tenancy with organization and team management
• Sentry error monitoring and performance tracking
• Plausible Analytics integration with configurable domains
• Responsive design with dark/light mode
• Comprehensive testing setup with Vitest

🛠 Tech Stack

• Framework: Next.js 16 (App Router) + React 19 + TypeScript
• Auth: Better Auth (with Organizations)
• Database: PostgreSQL (Neon) + Drizzle ORM
• Queue: BullMQ + Redis
• Billing: Stripe subscriptions
• Email: Resend + React Email
• Storage: Vercel Blob
• Monitoring: Sentry
• UI: Tailwind CSS + Shadcn UI

🤝 Contributing

We welcome contributions to improve Kosuke Template! This guide helps you set up your local development environment and submit pull requests.

Prerequisites

Before contributing, ensure you have:

• Node.js 20+: nodejs.org
• Bun: bun.sh - curl -fsSL https://bun.sh/install | bash
• Docker Desktop: docker.com/products/docker-desktop
• Git: git-scm.com

Required Service Accounts

You'll need accounts with these services (all have free tiers):

Service	Purpose	Sign Up	Free Tier
Stripe	Billing	stripe.com	Test mode
Resend	Email	resend.com	100 emails/day
Sentry	Monitoring	sentry.io	5k events/month
DigitalOcean	Storage	digitalocean.com	$5/month (250GB + 1TB transfer) ❌

Note: DigitalOcean Spaces is the only paid service. All other services have free tiers sufficient for development and testing.

Local Development Setup

1. Fork & Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/kosuke-template.git
cd kosuke-template

2. Install Dependencies (Local)

nvm use & bun install --frozen-lockfile

Note: nvm use reads the Node version from .nvmrc and switches to it. Run nvm install first if the version isn't installed.

3. Create Environment Variables

Create .env file in the root directory:

# Database (Local PostgreSQL via Docker)
POSTGRES_URL=postgres://postgres:postgres@localhost:54321/postgres

# Redis (via Docker on kosuke_network)
REDIS_URL=redis://redis:6379

# Stripe Billing
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PRO_PRICE_ID=price_...      # $20/month
STRIPE_BUSINESS_PRICE_ID=price_... # $200/month
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_SUCCESS_URL=http://localhost:3000/billing/success
STRIPE_CANCEL_URL=http://localhost:3000/settings/billing

# Resend Email (from resend.com/api-keys)
RESEND_API_KEY=re_...
[email protected]
RESEND_FROM_NAME=Kosuke Template

# Sentry (from sentry.io - optional for local dev)
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/...

# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Digital Ocean
S3_REGION=nyc3
S3_ENDPOINT=https://nyc3.digitaloceanspaces.com
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key

Get Your Credentials:

• Stripe: Create account at stripe.com → Get API keys → Create products and prices
• Resend: Sign up → Create API key → Use [email protected] for testing
• Sentry: Create project → Copy DSN (optional for local development)
• DigitalOcean: Create account → Create Spaces bucket → Generate API key & secret

4. Start All Services

docker compose up --build -d

This builds and starts all services on the kosuke_network:

• Next.js on http://localhost:3000
• PostgreSQL on localhost:54321
• Redis on localhost:6379
• Engine (FastAPI) on http://localhost:8000
• Background Workers (BullMQ)

🐳 Docker Development

The template includes a complete Docker setup for local development with hot reload:

Services:

• nextjs: Next.js dev server with hot reload (port 3000)
• workers: BullMQ background workers with hot reload
• postgres: PostgreSQL database (port 54321)
• redis: Redis for caching & jobs (port 6379)

Common Commands:

# Development Environment
bun run dev               # Start dev server

# Database Operations
bun run db:migrate        # Apply migrations
bun run db:seed           # Seed database
bun run db:generate       # Generate migrations (schema changes)
bun run db:push           # Push schema (prototyping)
bun run db:reset          # Reset database

# Testing & Quality
bun run test              # Run tests
bun run test:watch        # Run tests in watch mode
bun run test:coverage     # Generate test coverage report
bun run lint              # Run linter
bun run typecheck         # Run type check
bun run format            # Format code
bun run format:check      # Check code formatting
bun run knip              # Declutter project

# Email Templates
bun run email:dev         # Preview email templates (port 3001)

# Shadcn UI Management
bun run shadcn:update     # Update all shadcn components
bun run shadcn:check      # Check for available component updates

⚡ Background Jobs with BullMQ

This template includes a robust background job system powered by BullMQ and Redis:

• 🕐 Scheduled Jobs: Automatically syncs subscription data from Stripe daily at midnight
• ♻️ Retry Logic: Failed jobs automatically retry with exponential backoff
• 📊 Monitoring: Jobs tracked via console logs and Sentry error reporting
• ⚙️ Scalable: Add workers as needed to process jobs in parallel
• 🔧 Flexible: Easy to add new background jobs and scheduled tasks

Development:

• Workers run in a separate container (kosuke_template_workers)
• Both web server and workers have hot reload enabled
• Changes to code automatically restart services
• View worker logs: docker compose logs -f workers

📧 Email Templates with React Email

This template uses React Email for building beautiful, responsive email templates with React components and TypeScript.

Email Development Workflow

Services are already running via bun run dev. Open:

• Next.js: localhost:3000
• Email Preview: localhost:3001 (via bun run email:dev)

To preview email templates in another terminal:

bun run email:dev

Database Operations

Making Schema Changes

# 1. Edit lib/db/schema.ts
# 2. Generate migration
bun run db:generate

# 3. Review generated SQL in lib/db/migrations/
# 4. Apply migration
bun run db:migrate

Seed with test data

Populate your local database with realistic test data:

bun run db:seed

Test Users Created:

• [email protected] - Admin of "Jane Smith Co." (Free tier)
• [email protected] - Admin of "John Doe Ltd." (Free tier), Member of "Jane Smith Co."

Kosuke Verification Code:

When signing in with test users in development, use verification code: 424242

Testing

Run tests locally (requires dependencies installed):

# All tests
bun run test

# Watch mode (auto-rerun on changes)
bun run test:watch

# With coverage report
bun run test:coverage

Getting Help

• GitHub Issues: github.com/Kosuke-Org/kosuke-template/issues
• Discussions: Use GitHub Discussions for questions

📝 License

MIT License - see LICENSE file for details.