Overview
Modern, production-ready SaaS starter template for building full-stack React applications
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:
Verify Node.js is installed:
Should return something like
v24.x.y
(at the time of writing: 24.1.0) - Mac/Linux: Install via nvm:
-
Install ngrok for webhook testing:
-
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
andCLERK_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:
-
Install dependencies:
We use
--legacy-peer-deps
because some packages might have React 18 peer dependencies while we’re using React 19. -
Copy environment template:
-
Verify build works:
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: -
Test the basic setup:
-
Visit
http://localhost:5173
- you should see the homepage load successfully
Enable Database (Convex)
-
Set up Convex:
- Follow prompts to log in to Convex
- Create a new project when prompted (or select existing)
- This automatically creates a
.env.local
file with your Convex URL - Keep this terminal running (Convex development server)
-
Copy the environment variables from
.env.local
that Convex provides: -
Update your
config.ts
: -
Test the database connection:
Enable Authentication (Clerk + Convex)
-
Create a Clerk application:
- Go to clerk.dev and create an account
- Create a new application with a name like “Kaizen App”
- Select “React Router” as your framework
- Enable Email/Password and Google authentication methods
-
Set up 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
)
-
Add Clerk keys to your
.env.local
: -
CRITICAL: Add Clerk integration to Convex environment variables:
- Go to your Convex project dashboard
- Navigate to Settings → Environment Variables
- Add:
VITE_CLERK_FRONTEND_API_URL
with the Issuer URL from step 2 - This enables Convex to verify Clerk JWT tokens
-
Update your
config.ts
: -
Test authentication:
- You should see Sign In/Sign Up buttons
- Test the authentication flow
- Verify user data appears in Convex dashboard → Data → users table
Enable Payments (Polar.sh)
⚠️ Important: Use sandbox.polar.sh for testing with fake money first!
-
Create Polar.sh account and organization:
- Go to sandbox.polar.sh and create an account
- Create a new organization (e.g., “Kaizen Test”)
- Click Products → Create Product
- Set up a subscription product with pricing tiers
- Save the product
-
Get API credentials from Polar Dashboard:
Access Token:
- Go to Settings → Developers
- Click New Token
- Select all permissions, set no expiration
- Copy the token (starts with
polar_
)
Organization ID:
- Go to Settings → General
- Copy the Organization ID at the top (starts with
org_
)
-
Set up ngrok for local webhook testing:
Copy the HTTPS URL (e.g.,
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:
-
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
- Add
POLAR_WEBHOOK_SECRET=whsec_...
to Convex environment variables
- Get your Convex HTTP actions URL from dashboard (ends in
-
Update your
config.ts
: -
Test the full authentication + payment flow:
- Use your ngrok URL in browser (not localhost)
- Sign up/login with test account
- Go to pricing page and subscribe
- Use test card:
4242 4242 4242 4242
, any future date, any CVC - Verify redirect to success page and dashboard access
Enable Email (Resend) - Optional
-
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:
-
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
RESEND_WEBHOOK_SECRET=whsec_...
to Convex
- Get your Convex HTTP actions URL (ends in
-
Update your
config.ts
: -
Test email functionality:
- Navigate to
/dashboard
(must be authenticated) - Find “Test Email” form in dashboard
- Important: 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
- Navigate to
Enable AI Chat (OpenAI) - Optional
-
Add OpenAI API key:
-
Update your
config.ts
:
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
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:
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
Future Improvements (Coming soon…)
- Creating Waitlists with Clerk
- Feature flag integration + Recommended usage
- Integrate Zustand for state management client-side
- Implement stronger security rules with ArcJet (Bot detection, Rate limiting, Data Redaction, Email Validation, Application-level DDoS protection, etc.)
- Create a Biome security linting plugin for automatically finding and fixing security issues + integrate into Stack
- Add option for Kinde integration (for those who have more complex RBAC needs)