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. Create a fresh repository on GitHub (private - if you want to keep it private)
2. 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
   

3. 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.
4. Copy environment template:
   Copy

   cp .env.example .env.local
   

5. Verify build works:
   Copy

   npm run build
   

​

Start with Static Configuration (No 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
4. You can and should deploy this to Vercel now.

​

Enable Authentication and Convex

1. Update your config.ts:
   Copy

   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,
   }
   

2. 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 updates your .env.local file env vars (VITE_CONVEX_URL, CONVEX_DEPLOYMENT)
   • Keep this terminal running (Convex development server)
3. Add your Clerk keys to your .env.local file:
   Copy

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

4. 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)
5. 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
6. Also add this env var to your .env.local file:
   Copy

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

7. Shutdown and Restart your development server. Authentication should now be working.

​

Enable Payments (Polar.sh)

1. 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 }, // Enable polar.sh
     convex: { enabled: true },
   }
   ui: {
     showAuth: true,
     showDashboard: true,
     showChat: false,
     showPricing: true, // Show pricing page
   }
   

2. Run ngrok:
   Copy

   ngrok http 5173
   

   Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
3. Set your local frontend URL in your .env.local file:
   Copy

   FRONTEND_URL=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=...
   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
   • Copy the webhook secret and add it to your Convex Environment Variables:
   Copy

   POLAR_WEBHOOK_SECRET=whsec_...
   

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

1. Update your config.ts:
   Copy

   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 },
   }
   

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

   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
   

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

   RESEND_WEBHOOK_SECRET=whsec_...
   

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

​

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 }, // Enable openai
   }
   ui: {
     showChat: true,  // Show AI chat in dashboard
   }
   

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

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

​

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

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