@kozojs/cli

🔥 CLI to scaffold new Kozo Framework projects - The next-gen TypeScript Backend Framework with Zod Native Integration

Quick Start

# Using npx
npx @kozojs/cli my-app

# Or install globally
npm install -g @kozojs/cli
kozo my-app

Features

• 🚀 Interactive Setup - Choose database, template, and more
• 📦 Zero Config - Works out of the box
• 🔥 Hono-powered - Fastest HTTP framework
• 🛡️ Type-safe - Full TypeScript inference with Zod
• ⚡ High Performance - Ajv validation + fast-json-stringify serialization
• 📚 OpenAPI Auto-gen - Swagger docs out of the box
• 🗄️ Drizzle ORM - Best-in-class database toolkit

Usage

Create a new project

npx @kozojs/cli

Or with a project name:

npx @kozojs/cli my-awesome-api

Interactive prompts

The CLI will ask you:

1. Project name - Name of your new project
2. Template - Choose from available templates:
   • Complete Server - Full production-ready app (Auth, CRUD, Stats, Pagination)
   • Starter - Minimal setup with database integration
   • SaaS - Auth + Stripe + Email (coming soon)
   • E-commerce - Products + Orders (coming soon)
3. Database - PostgreSQL, MySQL, or SQLite (skipped for Complete template)
4. Package source - npm registry or local workspace
5. Install dependencies - Auto-run pnpm install

Project Structure

Starter Template (with Database)

my-app/
├── src/
│   ├── db/
│   │   ├── schema.ts     # Drizzle schema
│   │   └── index.ts      # Database client
│   ├── services/
│   │   └── index.ts      # Service definitions
│   └── index.ts          # Entry point with Zod native API
├── drizzle.config.ts
├── package.json
└── tsconfig.json

Complete Server Template

my-app/
├── src/
│   ├── data/
│   │   └── store.ts           # In-memory data store
│   ├── routes/
│   │   ├── auth/
│   │   │   └── index.ts       # Auth routes (login, me)
│   │   ├── users/
│   │   │   └── index.ts       # User CRUD routes
│   │   ├── posts/
│   │   │   └── index.ts       # Post routes
│   │   ├── health.ts          # Health check
│   │   └── stats.ts           # Statistics
│   ├── schemas/
│   │   ├── user.ts            # User schemas
│   │   ├── post.ts            # Post schemas
│   │   └── common.ts          # Common schemas
│   ├── utils/
│   │   └── helpers.ts         # Helper functions
│   └── index.ts               # Entry point
├── package.json
├── tsconfig.json
└── README.md

🚀 Complete Server Template

The Complete Server template generates a production-ready Kozo application with:

Features

• ✅ Authentication - Login endpoint with mock JWT
• ✅ User Management - Full CRUD (Create, Read, Update, Delete)
• ✅ Posts System - With authors, tags, and filtering
• ✅ Pagination - Query-based pagination for lists
• ✅ Statistics - System stats endpoint (users, posts, performance)
• ✅ Health Check - Fast-path health endpoint
• ✅ In-Memory Store - Ready-to-run without database setup

API Endpoints

• POST /auth/login - Authenticate user
• GET /auth/me - Get current user
• GET /users?page=1&limit=10 - List users (paginated)
• GET /users/:id - Get user by ID
• POST /users - Create new user
• PUT /users/:id - Update user
• DELETE /users/:id - Delete user
• GET /posts?published=true&tag=framework - List posts (filtered)
• GET /posts/:id - Get post with author
• POST /posts - Create new post
• GET /stats - System statistics
• GET /health - Health check

Performance Optimized

• Pre-compiled Zod schemas (no runtime overhead)
• Optimized handler closures
• Fast-path routes for simple endpoints
• Minimal context allocation

Perfect For

• Learning Kozo framework features
• Prototyping and demos
• Benchmarking and performance testing
• Starting point for production apps

✨ New Zod Native API

Kozo now features a brand new API with automatic TypeScript inference:

import { createKozo } from '@kozojs/core';
import { z } from 'zod';

const app = createKozo({
  port: 3000,
  openapi: {
    info: { title: 'My API', version: '1.0.0' }
  }
});

// Define schemas (compile-time only!)
const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string()
});

const CreateUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email()
});

// Routes with automatic type inference
app.get('/users', {
  response: z.array(UserSchema)
}, (c) => {
  // TypeScript SA che il return è UserSchema[]
  return users;
});

app.post('/users', {
  body: CreateUserSchema,
  response: UserSchema
}, (c) => {
  // TypeScript SA che c.body ha name: string, email: string
  const newUser = {
    id: Date.now().toString(),
    name: c.body.name,  // ✅ Type-checked
    email: c.body.email // ✅ Type-checked
  };
  return newUser;
});

app.get('/users/:id', {
  params: z.object({ id: z.string() }),
  response: UserSchema
}, (c) => {
  // TypeScript SA che c.params.id è string
  const user = users.find(u => u.id === c.params.id);
  return user;
});

console.log('🚀 Server: http://localhost:3000');
console.log('📚 API Docs: http://localhost:3000/swagger');
app.listen();

Performance Benefits

• Validation: Ajv compiled (5x faster than Zod runtime)
• Serialization: fast-json-stringify (2x faster than JSON.stringify)
• Type Safety: Complete TypeScript inference
• Zero Overhead: No runtime Zod parsing

Requirements

• Node.js >= 18.0.0
• pnpm (recommended) or npm

License

MIT