Overview

This page was last updated on: 7th July 2025

DO NOT upgrade any dependencies in your package.json for the core stack dependencies (Clerk, Convex, Polar.sh, etc.), unless you have a specific reason to and are following the official migration guides from each service. Upgrading packages without proper migration can break your authentication, database connections, and other critical functionality. The current versions in the boilerplate are tested and stable together.

Repo: https://github.com/ObaidUr-Rahmaan/kaizen

Pre-requisites

Frontend Knowledge (Have completed the Frontend section of the Software Engineer Roadmap) so that your base HTML, CSS, JS and React skills are up to par.
Fundamental Backend Systems Knowledge (Have completed the Systems Expert Fundamentals Course of the Software Engineer Roadmap)
Fundamental Tech Stack Knowledge (Have completed the Kaizen Tech Stack Tutorial)

Tech Stack

React Router v7 - Modern full-stack React framework with SSR
Convex - Real-time database and serverless functions
Clerk - Authentication as a Service Provider
Polar.sh - Subscription billing and payments
Resend - Email as a Service Provider
OpenAI - AI chat capabilities (optional)
Vercel - Deployments without worrying about infrastructure (Auto-Scaling, DDoS protection, etc.)

Cost of running this stack

All of the above services have generous free tiers.

Even as your product grows, the cost remains minimal (averaging $200-300/month with 10,000+ DAUs for 80%+ profit margin).

These 3rd party services abstract away significant infrastructure work in key areas (authentication, database, payments, etc.), letting you focus solely on building your product.

Building with Kaizen

Prerequisites

Install the latest stable version of Node.js (If you already have Node.js installed, this will override it):
- Mac/Linux: Install via nvm:
  nvm install stable
Verify Node.js is installed:
```
node -v
```
Should return something like v24.x.y (at the time of writing: 24.1.0)
Install ngrok for webhook testing:
```
brew install ngrok
```
Create a new empty GitHub repository for your project

Have the SSH repository URL ready (e.g., git@github.com:username/repo-name.git)

Make sure it’s the SSH URL, not the HTTPS URL!
Gather your Development API keys from the following services:

If you have your own agency and you’re building for a client, you’ll need to create all the below accounts for them using your own agency company email account and then transfer ownership to them later when the contract ends.

See the Account Management Guide for more information on how to do this.

Clerk (Authentication)
- Create an account at Clerk (or new ‘Application’ if you already have an account)
- Create a new Application and select “React Router” as your framework
- Enable Email/Password and Google authentication methods
- Copy your VITE_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY from the ‘API Keys’ section
- Add them to somewhere safe (ideally if you’re using a clipboard manager, you’ll be able to paste them into your .env file later)
Convex (Database)
- Create an account at Convex
- We’ll set this up in the next step when you clone the repo
Polar.sh (Subscriptions) - Optional for initial setup
- Create an account at sandbox.polar.sh
- Create a new organization
- Create a subscription plan
- Copy your API keys from Settings
- Add them to somewhere safe
Resend (Email) - Optional for initial setup
- Create an account at Resend
- Generate an API key from the API Keys section
- Add it to somewhere safe
OpenAI (AI Chat) - Optional
- Create an account at OpenAI
- Generate an API key from the API Keys section
- Copy your OPENAI_API_KEY
- Add it to somewhere safe

Clone and Setup Project

Clone the Kaizen repository and set up your project:

git clone https://github.com/ObaidUr-Rahmaan/kaizen.git your-project-name
cd your-project-name
rm -rf .git
git init
git remote add origin your-github-repo-url

Install dependencies:
```
npm install --legacy-peer-deps
```
We use --legacy-peer-deps because some packages might have React 18 peer dependencies while we’re using React 19.
Copy environment template:
```
cp .env.example .env.local
```
Verify build works:
```
npm run build
```

Configure Features Step by Step

Kaizen uses a progressive configuration approach where you can enable features one by one. Start with basic configuration and add services as needed.

Start with Static Configuration (No Services)

First, let’s make sure everything builds and runs without any external services:

Edit your config.ts file to disable all features:

features: {
  auth: false,
  payments: false,
  convex: false,
  email: false,
  monitoring: false,
}

Test the basic setup:
```
npm run build
npm run dev
```
Visit http://localhost:5173 - you should see the homepage load successfully
You can and should deploy this to Vercel now.

Enable Authentication and Convex

Update your config.ts:

features: {
  auth: true, // Enable authentication
  payments: false,
  convex: true, // Enable convex
  email: false,
  monitoring: false,
}
services: {
  convex: { enabled: true }, // Enable convex
  clerk: { enabled: true }, // Enable clerk
}
ui: {
  showAuth: true, // Show auth page
  showDashboard: true, // Show dashboard
  showChat: false,
  showPricing: false,
}

Set up Convex:
```
npx convex dev
```
- Follow prompts to log in to Convex
- Create a new project when prompted (or select existing)
- This automatically updates your .env.local file env vars (VITE_CONVEX_URL, CONVEX_DEPLOYMENT)
- Keep this terminal running (Convex development server)

Add your Clerk keys to your .env.local file:

VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

Configure Clerk JWT templates for Convex integration:
- In Clerk Dashboard: Go to Configure → JWT Templates
- Click New template → Convex
- Click Save (important - don’t forget this step!)
- Copy the Issuer URL (looks like https://your-app.clerk.accounts.dev)
Configure Convex to use your Clerk JWT template:
- Go to your Convex project dashboard (Make sure you’re on the ‘development’ environment)
- Navigate to Settings → Environment Variables
- Add: VITE_CLERK_FRONTEND_API_URL with the Issuer URL from step 4
- This enables Convex to verify Clerk JWT tokens

Also add this env var to your .env.local file:

NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

Authentication should now be working.

Enable Payments (Polar.sh)

Update your config.ts:

features: {
  auth: true,
  payments: true, // Enable payments
  convex: true,
  email: false,
  monitoring: false,
}
services: {
  clerk: { enabled: true },
  polar: { enabled: true }, // Enable polar.sh
  convex: { enabled: true },
}
ui: {
  showAuth: true,
  showDashboard: true,
  showChat: false,
  showPricing: true, // Show pricing page
}

Run ngrok:
```
ngrok http 5173
```
Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
Set your local frontend URL in your .env.local file:
```
FRONTEND_URL=https://abc123.ngrok.io
```
CRITICAL: Add environment variables to Convex Dashboard (not local .env):
- Go to your Convex project dashboard
- Navigate to Settings → Environment Variables
- Add these variables:
```
POLAR_ACCESS_TOKEN=polar_...
POLAR_ORGANIZATION_ID=org_...
FRONTEND_URL=https://abc123.ngrok.io  # Your ngrok URL, no trailing slash!
```
Configure webhook in Polar Dashboard:
- Get your Convex HTTP actions URL from dashboard (ends in .convex.site)
- Go to Settings → Webhooks → Add Endpoint
- URL: https://your-deployment.convex.site/payments/webhook
- Format: Raw
- Click Generate new secret and copy it
- Select all events and click Create
- Copy the webhook secret and add it to your Convex Environment Variables:
```
POLAR_WEBHOOK_SECRET=whsec_...
```
Test payments:
- Use your ngrok URL in browser (not localhost)
- Sign up/login with test account
- Click on the plan you created
- Use test card: 4242 4242 4242 4242, any future date, any CVC
- Verify redirect to success page and dashboard access

Enable Email (Resend)

Update your config.ts:

features: {
  auth: true,
  payments: true,
  convex: true,
  email: true, // Enable email
  monitoring: false,
}
services: {
  clerk: { enabled: true },
  polar: { enabled: true },
  convex: { enabled: true },
  resend: { enabled: true },
}

Create Resend account:
- Go to resend.com and create an account
- Generate an API key from API Keys section (select Full Access)
- Copy the API key (starts with re_)
Choose your email setup approach:

Option A: Quick Testing (No Domain Required)
- Use Resend’s built-in sandbox domain
- Sender email: onboarding@resend.dev (works immediately)
- Can only send to your Resend account email address
Option B: Custom Domain (Production Ready)
- Verify your own domain for branded emails
- Go to Domains → Add Domain → Enter your domain
- Add required DNS records (TXT, MX, CNAME) to your domain registrar
- Wait for verification (can take minutes to hours)
- Sender email: noreply@yourdomain.com (after verification)

CRITICAL: Add environment variables to Convex Dashboard (not local .env):

Go to your Convex project dashboard
Navigate to Settings → Environment Variables
Add these variables:

RESEND_API_KEY=re_...
SENDER_EMAIL=onboarding@resend.dev  # Use this for testing
# OR (after domain verification)
SENDER_EMAIL=noreply@yourdomain.com  # Use this for production
COMPANY_NAME=Your Company Name

Set up webhook for email events:
- Get your Convex HTTP actions URL (ends in .convex.site)
- In Resend dashboard → Webhooks → Add Endpoint
- URL: https://your-deployment.convex.site/resend-webhook
- Enable all email.* events
- Copy webhook secret and add it to your Convex Environment Variables:
```
RESEND_WEBHOOK_SECRET=whsec_...
```
Test email functionality:
- Navigate to /dashboard (must be authenticated)
- Find the “Test Email” form in dashboard
- Important: For local development, use your Resend account email address as recipient!
- Send test email and check spam folder (sandbox emails often go there)
- Verify success in Resend dashboard → Logs

🎉 Hooray! You’ve now successfully configured your app. You’re ready to start building and shipping features.

Enable AI Chat (OpenAI) - Optional

Add OpenAI API key:
```
OPENAI_API_KEY=sk-...
```

Update your config.ts:

services: {
  openai: { enabled: true }, // Enable openai
}
ui: {
  showChat: true,  // Show AI chat in dashboard
}

Add your OpenAI API key to your Convex Environment Variables:
- Go to your Convex project dashboard
- Navigate to Settings → Environment Variables
- Add: OPENAI_API_KEY=sk-...

Important: When returning to work on your project

Each time you restart ngrok, it generates a new URL. You must:

Update the FRONTEND_URL in your .env.local file with the new ngrok URL
Update your webhook endpoints in Polar Dashboard
Restart your dev server after updating the .env.local file

Failing to update these will cause webhooks to fail silently!

Remember to always use the ngrok URL when testing locally for webhook functionality, but you can use localhost:5173 for general development.

Building the Product

At this point, you should have a clean and beautiful landing page that explains the product and what it does, with authentication and optionally payments configured.

Now it’s time to add the main functionality of your product:

Dashboard: Users get redirected here after signing up
Core Features: The main value proposition of your SaaS
Settings: User profile management and subscription handling

We’ve got a dedicated guide page related to building clean and beautiful UIs very quickly: Rapid UI Prototyping

See the ‘The v0 + Cursor Workflow (Recommended)’ section

Testing Your Application

Kaizen includes comprehensive testing setup with Vitest and Playwright:

Run All Tests

npm run test:all

Unit Tests (Development)

npm run test:watch    # Watch mode
npm run test:ui       # Visual UI

End-to-End Tests

npm run test:e2e      # Run once
npm run test:e2e:ui   # Interactive UI

Tests are configured as non-blocking by default, meaning deployments can proceed even if tests fail. This ensures development velocity while still providing test feedback.

Deploying the App to Production

You’ll need to purchase a domain before deploying to production. Services like Clerk and Polar require a verified domain for production environments. Purchase a domain from providers like Namecheap, Porkbun, GoDaddy, or Google Domains before proceeding with production deployment.

When you’re ready to deploy your application to production, follow our comprehensive deployment guide:

Deploy to Production Guide

The guide covers everything you need for a successful production deployment:

Domain purchase and setup
Production database configuration (Convex)
Production authentication setup (Clerk)
Production subscription setup (Polar.sh)
Vercel deployment
Post-deployment verification

Setup & Configuration

Development & Deployment

Optimisations

Pre-requisites

Tech Stack

Cost of running this stack

Building with Kaizen

Start with Static Configuration (No Services)

Enable Authentication and Convex

Enable Payments (Polar.sh)

Enable Email (Resend)

Enable AI Chat (OpenAI) - Optional

Run All Tests

Unit Tests (Development)

End-to-End Tests

Setup & Configuration

Development & Deployment

Optimisations

​Pre-requisites

​Tech Stack

​Cost of running this stack

​Building with Kaizen

​Start with Static Configuration (No Services)

​Enable Authentication and Convex

​Enable Payments (Polar.sh)

​Enable Email (Resend)

​Enable AI Chat (OpenAI) - Optional

​Run All Tests

​Unit Tests (Development)

​End-to-End Tests

Pre-requisites

Tech Stack

Cost of running this stack

Building with Kaizen

Start with Static Configuration (No Services)

Enable Authentication and Convex

Enable Payments (Polar.sh)

Enable Email (Resend)

Enable AI Chat (OpenAI) - Optional

Run All Tests

Unit Tests (Development)

End-to-End Tests