Skip to main content
This guide walks you through setting up a complete development environment for Kaizen, including all dependencies, environment variables, and development tools.

​
Prerequisites

Before starting, ensure you have the following installed:
  • Node.js (v18 or later)
  • pnpm (v8 or later) - Kaizen uses pnpm as its package manager
  • Git for version control

​
Installation

1

Clone the repository

Clone the Kaizen repository to your local machine:
git clone <repository-url>
cd kaizen
2

Install dependencies

Install all project dependencies using pnpm:
pnpm install
This will install:
  • Angular 21 framework and CLI
  • Convex client and Angular integration
  • Clerk authentication library
  • PrimeNG component library
  • TailwindCSS for styling
3

Configure environment variables

Create environment configuration files in src/environments/:src/environments/environment.development.ts
export const environment = {
  production: false,
  convexPublicUrl: 'your-convex-url',
  clerkPublicKey: 'your-clerk-publishable-key'
};
src/environments/environment.ts
export const environment = {
  production: true,
  convexPublicUrl: 'your-convex-url',
  clerkPublicKey: 'your-clerk-publishable-key'
};
The development environment file is automatically used when running ng serve due to the file replacement configuration in angular.json.
4

Set up Convex backend

Initialize and deploy the Convex backend:
npx convex dev
This command:
  • Creates a new Convex project (first time only)
  • Generates type definitions in convex/_generated/
  • Starts the Convex development server
  • Watches for changes to your Convex functions
Keep this terminal window open - it needs to run alongside your Angular dev server.
5

Configure Clerk authentication

Set up Clerk for authentication:
  1. Create a Clerk application at clerk.com
  2. Create a JWT template named “convex” in your Clerk dashboard
  3. Copy the Issuer URL and set it as CLERK_JWT_ISSUER_DOMAIN in your Convex dashboard
  4. Copy your Clerk publishable key to your environment files
Update convex/auth.config.ts to use the environment variable:
import { AuthConfig } from 'convex/server';

export default {
  providers: [
    {
      domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
      applicationID: 'convex',
    },
  ],
} satisfies AuthConfig;
6

Start the development server

Start the Angular development server:
pnpm start
# or
ng serve
The application will be available at http://localhost:4200.
The dev server supports hot module replacement - changes to your code will automatically reload the browser.

​
Available scripts

Kaizen provides several npm scripts for development:
ScriptCommandDescription
startng serveStart development server
buildng buildBuild for production
watchng build --watch --configuration developmentBuild in watch mode
testng testRun unit tests with Karma

​
Development tools

​
VS Code configuration

The project includes recommended VS Code settings in .vscode/:
  • extensions.json - Recommended extensions for Angular development
  • launch.json - Debug configurations for Chrome
  • tasks.json - Build and serve tasks

​
Angular configuration

Key Angular CLI configurations in angular.json: 
{
  "schematics": {
    "@schematics/angular:component": {
      "skipTests": true,
      "inlineStyle": true,
      "standalone": true
    },
    "@schematics/angular:service": {
      "skipTests": true
    }
  }
}
All components are generated as standalone components by default.

​
TypeScript configuration

The project uses strict TypeScript settings (tsconfig.json):
  • strict: true - All strict type checking options enabled
  • noImplicitOverride: true - Require explicit override keywords
  • noImplicitReturns: true - Ensure all code paths return values
  • experimentalDecorators: true - Required for Angular decorators

​
Troubleshooting

If you see connection errors to Convex:
  1. Ensure npx convex dev is running
  2. Verify convexPublicUrl in your environment file matches your Convex dashboard
  3. Check that your network allows WebSocket connections
Common Clerk issues:
  1. Verify clerkPublicKey is correct in your environment file
  2. Ensure the JWT template “convex” is configured in Clerk
  3. Check that CLERK_JWT_ISSUER_DOMAIN is set in Convex dashboard
  4. Clear browser cookies and try again
If you encounter build errors:
  1. Delete node_modules and pnpm-lock.yaml
  2. Run pnpm install again
  3. Clear Angular cache: rm -rf .angular
  4. Restart your development server

​
Next steps

Project structure

Learn about the file and folder organization

State management

Understand how Angular signals manage state

Build docs developers (and LLMs) love

Get started for freeTalk to us