Overview

1. Install the latest stable version of Node.js (If you already have Node.js installed, this will override it):

   • Mac/Linux: Install via nvm:
     Copy

     nvm install stable
     

   Verify Node.js is installed:

   Copy

   node -v
   

   Should return something like v24.x.y (at the time of writing: 24.1.0)

2. Install ngrok for webhook testing:

   Copy

   brew install ngrok
   

3. 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!

4. Gather your Development API keys from the following services:

• 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

1. Clone the Kaizen repository and set up your project:

   Copy

   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
   

2. Install dependencies:

   Copy

   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.

3. Copy environment template:

   Copy

   cp .env.example .env.local
   

4. Verify build works:

   Copy

   npm run build
   

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:

1. Edit your config.ts file to disable all features:

   Copy

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

2. Test the basic setup:

   Copy

   npm run build
   npm run dev
   

3. Visit http://localhost:5173 - you should see the homepage load successfully

​

Enable Database (Convex)

1. Set up Convex:

   Copy

   npx convex dev
   

   • 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)

2. Copy the environment variables from .env.local that Convex provides:

   Copy

   # These are automatically created by `npx convex dev`
   VITE_CONVEX_URL=https://your-deployment.convex.cloud
   CONVEX_DEPLOYMENT=your-deployment-name
   NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
   

3. Update your config.ts:

   Copy

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

4. Test the database connection:

   Copy

   npm run build
   npm run dev
   

​

Enable Authentication (Clerk + Convex)

1. 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

2. 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)

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

   Copy

   VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
   CLERK_SECRET_KEY=sk_test_...
   VITE_CLERK_FRONTEND_API_URL=https://your-app.clerk.accounts.dev
   

4. 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

5. Update your config.ts:

   Copy

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

6. Test authentication:

   Copy

   npm run build
   npm run dev
   

   • 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!

1. 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

2. 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_)

3. Set up ngrok for local webhook testing:

   Copy

   ngrok http 5173
   

   Copy the HTTPS URL (e.g., https://abc123.ngrok.io)

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

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

   POLAR_ACCESS_TOKEN=polar_...
   POLAR_ORGANIZATION_ID=org_...
   FRONTEND_URL=https://abc123.ngrok.io  # Your ngrok URL, no trailing slash
   

5. 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

6. Update your config.ts:

   Copy

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

7. 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

1. 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_)

2. 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)

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

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

   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
   

4. 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

5. Update your config.ts:

   Copy

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

6. 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

​

Enable AI Chat (OpenAI) - Optional

1. Add OpenAI API key:

   Copy

   OPENAI_API_KEY=sk-...
   

2. Update your config.ts:

   Copy

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

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:

1. Dashboard: Users get redirected here after signing up
2. Core Features: The main value proposition of your SaaS
3. 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

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

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