Perfect Template

A modern Next.js SaaS template with progressive feature activation. Start with core features and add services as needed.

Quick Start

# Clone the template
git clone https://github.com/yourusername/perfect-template.git
cd perfect-template

# Install dependencies
npm install

# Run interactive setup
npm run setup

# Start development server
npm run dev

Interactive Setup CLI

Run npm run setup to configure your services:

🚀 Perfect Template Setup

Which services would you like to set up?

Clerk Authentication (y/N): y
Convex Database (y/N): y
Autumn Billing (y/N): n
AI Integration (optional) (y/N): y
Email (Resend) (y/N): y

The CLI will:

• ✅ Install required packages
• ✅ Create necessary files and folders
• ✅ Generate .env.local with placeholders
• ✅ Set up API routes and components

Services

Core (Always Included)

• Next.js 15 with App Router
• TypeScript
• Tailwind CSS
• shadcn/ui components

Optional Services (Add via CLI)

🔐 Clerk Authentication

• User authentication and management
• Social logins (Google, GitHub, etc.)
• Multi-factor authentication
• User profiles and metadata

🗄️ Convex Database

• Real-time database
• Serverless functions
• File storage
• Automatic TypeScript types

💳 Autumn Billing

• Subscription management
• Usage-based billing
• Payment processing
• Customer portal

🤖 AI Integration

• OpenAI GPT models
• Anthropic Claude
• Streaming responses
• Token usage tracking

📧 Email (Resend)

• Transactional emails
• React email templates
• Email delivery tracking
• Domain verification

Progressive Architecture

The template uses a hierarchical service structure:

1. Core Mode: Just Next.js - no auth or database
2. Database Mode: Automatically enables auth when you add Convex
3. Full Mode: All services enabled

Services activate based on environment variables in .env.local:

# No keys = Core mode
# Add Convex keys = Auth + Database enabled
# Add other keys = Additional features enabled

Environment Variables

After running setup, add your API keys to .env.local:

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# Convex Database
NEXT_PUBLIC_CONVEX_URL=https://...convex.cloud
CONVEX_DEPLOY_KEY=...

# Autumn Billing
NEXT_PUBLIC_AUTUMN_ORG_ID=org_...
AUTUMN_API_KEY=ak_...

# AI Integration
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Email
RESEND_API_KEY=re_...

Quick Links to Get API Keys:

• 🔐 Clerk Dashboard
• 🗄️ Convex Dashboard
• 💳 Autumn Dashboard
• 🤖 OpenAI Platform
• 🧠 Anthropic Console
• 📧 Resend Dashboard

Project Structure

perfect-template/
├── src/
│   ├── app/              # Next.js app router
│   │   ├── api/          # API routes
│   │   ├── (auth)/       # Auth pages (if enabled)
│   │   └── dashboard/    # Main app
│   ├── components/       # React components
│   └── lib/             # Utilities
├── convex/              # Database (if enabled)
├── emails/              # Email templates (if enabled)
├── config.ts            # Service configuration
└── setup.js             # CLI setup script

Development

# Start dev server
npm run dev

# Build for production
npm run build

# Run production server
npm start

# Re-run setup to add more services
npm run setup

How the CLI Works

The setup.js script:

1. Prompts for which services to enable
2. Installs only the packages you need
3. Creates service-specific files:
   • Auth: Sign-in/up pages
   • Database: Convex configuration
   • Billing: Webhook endpoints
   • AI: Chat API routes
   • Email: Templates and send endpoint
4. Generates .env.local with the right variables
5. Provides links to get your API keys

Manual Service Addition

If you prefer manual setup over the CLI:

Clerk

npm install @clerk/nextjs
# Add middleware, providers, and auth pages

Convex

npm install convex convex-react-clerk
npx convex dev

Autumn

# No SDK needed, uses REST API
# Create webhook endpoint at /api/autumn/webhook

AI

npm install ai @ai-sdk/openai @ai-sdk/anthropic
# Create chat endpoint at /api/chat

Email

npm install resend @react-email/components
# Create templates in /emails

Deployment

Deploy to Vercel with one click:

Remember to add your environment variables in the Vercel dashboard.

License

MIT