Menu
Initialize new Kagaribi projects with optional database and deployment target configuration
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | kagaribi-setup |
| description | Initialize new Kagaribi projects with optional database and deployment target configuration |
Guide Claude through initializing a new Kagaribi project with appropriate configuration based on user requirements.
The root package is the only special package with three key responsibilities:
Entry Point
Authentication & Authorization
Deployment Information Management
url field in kagaribi.config.tsABSOLUTE RULE: .ts files MUST NEVER contain HTML template literals. ALWAYS use .tsx files with React/JSX components for views.
❌ ABSOLUTELY FORBIDDEN:
// ❌ NEVER write HTML template literals in .ts files
import { html } from 'hono/html';
app.get('/', (c) => c.html(html`<html>...</html>`));
// ❌ ALSO FORBIDDEN - Any HTML strings
app.get('/page', (c) => {
return c.html(`<html><body><h1>Title</h1></body></html>`);
});
✅ CORRECT OPTIONS:
For APIs - Use .ts files:
// ✅ .ts files for JSON APIs
app.get('/api/data', (c) => c.json({ message: 'API response' }));
For views - Use .tsx files:
// ✅ Create views/HomePage.tsx
import { FC } from 'hono/jsx';
export const HomePage: FC = () => {
return (
<html>
<body>
<h1>Home</h1>
</body>
</html>
);
};
// ✅ Use .tsx for routes that render views
// src/index.tsx (note: .tsx extension)
import { Hono } from 'hono';
import { HomePage } from '../views/HomePage';
const app = new Hono()
.get('/', (c) => c.html(<HomePage />));
export default app;
Why This Rule Exists:
See: Views Guide for detailed documentation.
Maintain Independence
Clear Scope of Responsibility
users (user management), payments (payment processing), notifications (notifications)Communication Through Root Package
DB models are shared across the entire application
db/schema.ts - All table definitionsdb/models/ - Helper functions for each tableimport { schema } from '../../../db/index.js'Why share?
Root package provides authentication and passes information to packages via JWT
Client → Root Package
Root Package → Each Package
Authorization headerDifferences by Environment
When a user wants to create a new project, gather these requirements:
node - Traditional Node.js servers, VPS (default)cloudflare - Cloudflare Workers (edge computing)lambda - AWS Lambda (serverless)cloudrun - Google Cloud Run (containers)deno - Deno Deploy (edge runtime)npx kagaribi init <name> [--db postgresql|mysql|sqlite] [--driver libsql|d1|sqlite-cloud] [--node|--cloudflare|--lambda|--cloudrun|--deno]
--driver is only valid when --db sqlite is used. The default when omitted is libsql.
Examples:
# Basic project with Node.js target (default)
npx kagaribi init my-api
# Project with PostgreSQL database
npx kagaribi init blog-api --db postgresql
# Project with MySQL and Cloudflare Workers target
npx kagaribi init shop-api --db mysql --cloudflare
# Project without database, targeting AWS Lambda
npx kagaribi init webhook-handler --lambda
# Project with Cloudflare D1 (SQLite on Cloudflare Workers)
npx kagaribi init edge-api --db sqlite --driver d1 --cloudflare
# Project with libsql (Turso)
npx kagaribi init turso-api --db sqlite --driver libsql
package.json - Dependencies and scriptskagaribi.config.ts - Deployment configurationtsconfig.json - TypeScript configuration.gitignore - Standard ignore patternspnpm-workspace.yaml - pnpm workspace configurationpackages/root/kagaribi.package.ts - Root package manifestpackages/root/src/index.ts - Minimal Hono app with / and /health routes--db Flagdb/schema.ts - Drizzle ORM schema definitionsdb/index.ts - Database connection helper (initDb, getDb)db/models/index.ts - Model exportsdrizzle.config.ts - Drizzle Kit configuration.env.example - Environment variable templatebuild:db, db:generate, db:migrate, db:studiocd <project-name>
pnpm install
# Copy example environment file
cp .env.example .env
# Edit .env and set DATABASE_URL
# PostgreSQL example: postgresql://user:password@localhost:5432/dbname
# MySQL example: mysql://user:password@localhost:3306/dbname
# Generate migration files from schema
pnpm run db:generate
# Apply migrations to database
pnpm run db:migrate
pnpm run dev
# Server starts at http://localhost:3000
User requirement: "Create a simple REST API for webhooks"
Commands:
npx kagaribi init webhook-api --node
cd webhook-api
pnpm install
pnpm run dev
What you get:
User requirement: "Build a blog backend with PostgreSQL"
Commands:
npx kagaribi init blog-api --db postgresql --node
cd blog-api
pnpm install
cp .env.example .env
# Edit .env: DATABASE_URL=postgresql://user:pass@localhost:5432/blog
pnpm run db:generate
pnpm run db:migrate
pnpm run dev
What you get:
getDb(), initDb())User requirement: "Create a serverless API on Cloudflare Workers with MySQL"
Commands:
npx kagaribi init serverless-api --db mysql --cloudflare
cd serverless-api
pnpm install
cp .env.example .env
# Edit .env: DATABASE_URL=mysql://user:pass@host:3306/dbname
pnpm run db:generate
pnpm run db:migrate
pnpm run dev
What you get:
User requirement: "Build an API on Cloudflare Workers using D1 (SQLite)"
Commands:
npx kagaribi init d1-api --db sqlite --driver d1 --cloudflare
cd d1-api
pnpm install
npx wrangler d1 create my-database # Create D1 database
# Update wrangler.toml with database_id and binding name
npx drizzle-kit generate # Generate migrations
npx wrangler d1 migrations apply my-database --local # Apply locally
pnpm run dev
What you get:
drizzle-orm/d1)wrangler.toml with D1 binding configurationDATABASE_URL env var — uses D1 binding object insteadkagaribi.config.tsimport { defineConfig } from '@kagaribi/core';
export default defineConfig({
packages: {
root: {
target: 'node', // Deployment target
},
},
environments: {
development: {
packages: {
'*': { colocateWith: 'root' }, // All packages run together
},
},
production: {
packages: {
// Define production deployment strategy
},
},
},
});
db/schema.ts (with --db)import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core';
// Example table (auto-generated)
export const users = pgTable('users', {
id: serial('id').primaryKey(),
name: text('name').notNull(),
email: text('email').notNull().unique(),
createdAt: timestamp('created_at').defaultNow().notNull(),
});
db/index.ts (with --db)import { drizzle } from 'drizzle-orm/node-postgres';
import { createDbHelper } from '@kagaribi/core';
import * as schema from './schema.js';
const { initDb, getDb } = createDbHelper((url) => drizzle(url, { schema }));
export { initDb, getDb, schema };
Issue: pnpm install fails
Issue: Database connection fails
DATABASE_URL format and database server is runningIssue: Migration generation fails
db/schema.ts for syntax errorsAfter successful project initialization: