koan-quickstart
Zero to first Koan app in under 10 minutes (S0 + S1 patterns)
When & Why to Use This Skill
This Claude skill facilitates rapid .NET application development using the Koan framework. It enables developers to transition from a blank slate to a functional web application in under 10 minutes by automating project scaffolding, entity creation, and CRUD API generation. By implementing S0 and S1 patterns, it streamlines the development of RESTful services with minimal configuration and provides a clear path for scaling from local JSON storage to production-grade databases like PostgreSQL.
Use Cases
- Rapid Prototyping: Quickly scaffold a new .NET web project with pre-configured Koan dependencies and boilerplate code for immediate development.
- Automated CRUD API Development: Generate full GET, POST, PUT, DELETE, and PATCH endpoints automatically by simply defining entity models.
- Database Provider Transparency: Seamlessly switch between JSON file storage and PostgreSQL databases without modifying existing entity or controller logic.
- Educational Onboarding: Serve as a step-by-step guide for developers to learn the core principles of the Koan framework and modern .NET API architecture.
| name | koan-quickstart |
|---|---|
| description | Zero to first Koan app in under 10 minutes (S0 + S1 patterns) |
Koan Quickstart
Core Principle
Get productive in under 10 minutes. Create entities, save data, expose APIs with minimal code.
10-Minute First App
Step 1: Create Project (1 min)
dotnet new web -n MyKoanApp
cd MyKoanApp
dotnet add package Koan.Core --version 0.6.3
dotnet add package Koan.Data.Core --version 0.6.3
dotnet add package Koan.Data.Connector.Json --version 0.6.3
dotnet add package Koan.Web --version 0.6.3
Step 2: Minimal Program.cs (1 min)
using Koan.Core;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddKoan();
var app = builder.Build();
app.Run();
Step 3: Create Entity (2 min)
// Models/Todo.cs
using Koan.Data.Core;
public class Todo : Entity<Todo>
{
public string Title { get; set; } = "";
public bool Completed { get; set; }
}
Step 4: Create Controller (2 min)
// Controllers/TodosController.cs
using Koan.Web;
using Microsoft.AspNetCore.Mvc;
[Route("api/[controller]")]
public class TodosController : EntityController<Todo>
{
// Full CRUD API auto-generated!
}
Step 5: Run and Test (4 min)
dotnet run
# Test endpoints:
curl http://localhost:5000/api/todos
curl -X POST http://localhost:5000/api/todos \
-H "Content-Type: application/json" \
-d '{"title":"First task","completed":false}'
Done! You now have a working CRUD API with:
- ✅ Auto GUID v7 IDs
- ✅ GET/POST/PUT/DELETE/PATCH endpoints
- ✅ JSON file storage
- ✅ Zero configuration
Next Steps
Add Relationships (5 min)
public class User : Entity<User>
{
public string Name { get; set; } = "";
}
public class Todo : Entity<Todo>
{
public string Title { get; set; } = "";
public string UserId { get; set; } = "";
public Task<User?> GetUser(CancellationToken ct = default) =>
User.Get(UserId, ct);
}
Switch to Real Database (2 min)
# Add PostgreSQL
dotnet add package Koan.Data.Connector.Postgres
# Update appsettings.json
{
"Koan": {
"Data": {
"Sources": {
"Default": {
"Adapter": "postgres",
"ConnectionString": "Host=localhost;Database=myapp;Username=koan;Password=dev"
}
}
}
}
}
# Entity code unchanged! Provider transparency.
When This Skill Applies
- ✅ Starting new projects
- ✅ Learning Koan basics
- ✅ Quick prototypes
- ✅ Proof of concepts
Reference Documentation
- Sample:
samples/S0.ConsoleJsonRepo/(Minimal 20-line example) - Sample:
samples/S1.Web/(Full web app with relationships) - Getting Started:
docs/getting-started/overview.md