Skip to main content
Get your local development environment set up and start building with Kaizen’s incremental idle game architecture.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 18.x or higher
  • pnpm 8.x or higher (recommended package manager)
  • Git for cloning the repository
Kaizen uses pnpm for faster, more efficient dependency management. If you don’t have it installed, run npm install -g pnpm.

​
Installation

1

Clone the repository

Clone the Kaizen repository to your local machine:
git clone https://github.com/yourusername/kaizen.git
cd kaizen
2

Install dependencies

Install all required packages using pnpm:
pnpm install
This will install the core dependencies including:
  • Angular 21 - Frontend framework
  • Convex - Real-time backend and database
  • Clerk - Authentication provider
  • PrimeNG - UI component library
  • TailwindCSS - Utility-first styling
3

Set up environment variables

Create an environment configuration file for development:
touch src/environments/environment.development.ts
Add your Convex and Clerk credentials:
src/environments/environment.development.ts
export const environment = {
  convexPublicUrl: 'https://your-deployment.convex.cloud',
  clerkPublicKey: 'pk_test_your_clerk_publishable_key',
};
Never commit your environment files to version control. The src/environments/ directory is already gitignored.
4

Configure Convex backend

Initialize and deploy your Convex backend:
npx convex dev
This command will:
  1. Create a new Convex project (if you haven’t already)
  2. Generate your Convex deployment URL
  3. Start watching for backend changes
  4. Sync your schema and functions to the cloud
Keep the convex dev process running in a separate terminal. It enables hot-reloading for your backend functions.
Copy the deployment URL from the output and update your environment.development.ts file with the convexPublicUrl value.
5

Configure Clerk authentication

Set up Clerk to handle user authentication:
  1. Create a free account at clerk.com
  2. Create a new application
  3. Copy your Publishable Key and add it to environment.development.ts
  4. In the Clerk dashboard, navigate to JWT Templates
  5. Create a new template named convex
  6. Copy the Issuer URL from the template
Add the Clerk JWT issuer to your Convex deployment:
npx convex env set CLERK_JWT_ISSUER_DOMAIN "your-clerk-issuer-url"
The Convex auth configuration in convex/auth.config.ts uses this environment variable to validate JWTs from Clerk.
6

Start the development server

With Convex running in one terminal, start the Angular development server in another:
pnpm start
Or use the Angular CLI directly:
ng serve
The application will be available at http://localhost:4200.

​
Verify your setup

Once the development server is running, open your browser to http://localhost:4200. You should see:
  1. The Kaizen landing page or authentication prompt
  2. Clerk authentication working (sign up/sign in buttons functional)
  3. No console errors related to Convex or Clerk connections
On first run, you’ll need to create an account to access the game. Clerk handles all authentication flows including email verification.

​
Available scripts

Kaizen includes several npm scripts for common development tasks:
CommandDescription
pnpm startStart the development server on port 4200
pnpm buildBuild the production bundle
pnpm watchBuild and watch for changes in development mode
pnpm testRun the Jasmine/Karma test suite

​
Project structure

kaizen/
├── src/
│   ├── app/              # Angular application code
│   │   ├── components/   # Reusable UI components
│   │   ├── services/     # Business logic and state management
│   │   └── routes/       # Route definitions
│   └── environments/     # Environment configurations (gitignored)
├── convex/
│   ├── schema.ts         # Database schema definitions
│   ├── character.ts      # Character progression functions
│   ├── goldUpgrades.ts   # Gold upgrade mutations
│   ├── prestigeUpgrades.ts # Prestige system functions
│   └── auth.config.ts    # Clerk authentication config
└── public/               # Static assets

​
Next steps

Now that your development environment is ready:

Architecture

Learn about Kaizen’s architecture and game mechanics

Game mechanics

Explore character progression, upgrades, and prestige

State management

Understand how Convex powers real-time game state

Backend integration

Deep dive into Clerk integration and user management

​
Troubleshooting

​
Convex connection failed

If you see errors about Convex connection failures:
  • Ensure convex dev is running in a separate terminal
  • Verify the convexPublicUrl in your environment file matches your deployment URL
  • Check that your deployment is active in the Convex dashboard

​
Clerk authentication not working

If authentication doesn’t work:
  • Verify your clerkPublicKey is correct and starts with pk_test_ or pk_live_
  • Ensure you’ve created the convex JWT template in Clerk
  • Confirm the CLERK_JWT_ISSUER_DOMAIN environment variable is set in Convex

​
Port already in use

If port 4200 is already in use:
  • Stop other Angular applications running on that port
  • Or specify a different port: ng serve --port 4201

Build docs developers (and LLMs) love

Get started for freeTalk to us