|
| 1 | +# Kori |
| 2 | + |
| 3 | +A modern, type-safe web framework for TypeScript, built on [Hono](https://hono.dev/)'s battle-tested router. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- Fast and lightweight routing powered by Hono's router |
| 8 | +- Full TypeScript type inference throughout your application |
| 9 | +- Automatic OpenAPI specification generation |
| 10 | +- Schema validation with Zod and other libraries |
| 11 | +- Extensible plugin architecture |
| 12 | + |
| 13 | +## Installation |
| 14 | + |
| 15 | +```bash |
| 16 | +npm install @korix/kori |
| 17 | +``` |
| 18 | + |
| 19 | +## Quick Example |
| 20 | + |
| 21 | +```typescript |
| 22 | +import { createKori } from '@korix/kori'; |
| 23 | + |
| 24 | +const app = createKori() |
| 25 | + .get('/hello/:name', (ctx) => { |
| 26 | + const { name } = ctx.req.pathParams(); |
| 27 | + return ctx.res.json({ message: `Hello, ${name}!` }); |
| 28 | + }) |
| 29 | + .post('/users', async (ctx) => { |
| 30 | + const body = await ctx.req.bodyJson(); |
| 31 | + return ctx.res.status(201).json({ id: 1, ...body }); |
| 32 | + }); |
| 33 | + |
| 34 | +// Generate the fetch handler |
| 35 | +const { fetchHandler } = await app.generate().onStart(); |
| 36 | + |
| 37 | +// Use with any platform that supports Fetch API |
| 38 | +const response = await fetchHandler(new Request('http://localhost/hello/world')); |
| 39 | +``` |
| 40 | + |
| 41 | +## With Validation |
| 42 | + |
| 43 | +```typescript |
| 44 | +import { createKori } from '@korix/kori'; |
| 45 | +import { zodRequestSchema, zodResponseSchema, enableZodRequestValidation } from '@korix/zod-schema-adapter'; |
| 46 | +import { z } from 'zod'; |
| 47 | + |
| 48 | +const app = createKori({ |
| 49 | + ...enableZodRequestValidation(), |
| 50 | +}); |
| 51 | + |
| 52 | +app.post('/users', { |
| 53 | + requestSchema: zodRequestSchema({ |
| 54 | + body: z.object({ |
| 55 | + name: z.string(), |
| 56 | + age: z.number(), |
| 57 | + }), |
| 58 | + }), |
| 59 | + responseSchema: zodResponseSchema({ |
| 60 | + 201: z.object({ |
| 61 | + id: z.number(), |
| 62 | + name: z.string(), |
| 63 | + age: z.number(), |
| 64 | + }), |
| 65 | + }), |
| 66 | + handler: (ctx) => { |
| 67 | + // Types are automatically inferred from schemas |
| 68 | + const { name, age } = ctx.req.validatedBody(); |
| 69 | + return ctx.res.status(201).json({ id: 1, name, age }); |
| 70 | + }, |
| 71 | +}); |
| 72 | +``` |
| 73 | + |
| 74 | +## And OpenAPI |
| 75 | + |
| 76 | +```typescript |
| 77 | +import { createKori } from '@korix/kori'; |
| 78 | +import { zodOpenApiPlugin, openApiMeta } from '@korix/zod-openapi-plugin'; |
| 79 | +import { swaggerUiPlugin } from '@korix/openapi-swagger-ui-plugin'; |
| 80 | +import { startNodejsServer } from '@korix/nodejs-server'; |
| 81 | + |
| 82 | +const app = createKori() |
| 83 | + .applyPlugin( |
| 84 | + zodOpenApiPlugin({ |
| 85 | + info: { title: 'My API', version: '1.0.0' }, |
| 86 | + }), |
| 87 | + ) |
| 88 | + .applyPlugin(swaggerUiPlugin()) |
| 89 | + .get('/hello/:name', { |
| 90 | + pluginMeta: openApiMeta({ |
| 91 | + summary: 'Say hello', |
| 92 | + description: 'Returns a personalized greeting', |
| 93 | + tags: ['Greetings'], |
| 94 | + }), |
| 95 | + handler: (ctx) => { |
| 96 | + const { name } = ctx.req.pathParams(); |
| 97 | + return ctx.res.json({ message: `Hello, ${name}!` }); |
| 98 | + }, |
| 99 | + }); |
| 100 | + |
| 101 | +await startNodejsServer(app, { port: 3000 }); |
| 102 | + |
| 103 | +// Visit http://localhost:3000/docs for interactive API documentation |
| 104 | +``` |
| 105 | + |
| 106 | +## Documentation |
| 107 | + |
| 108 | +📖 [Read the full documentation](https://bufferings.github.io/kori) |
| 109 | + |
| 110 | +## Packages |
| 111 | + |
| 112 | +- [`@korix/kori`](./packages/kori) - Core framework |
| 113 | +- [`@korix/zod-openapi-plugin`](./packages/zod-openapi-plugin) - Zod schema validation with OpenAPI generation |
| 114 | +- [`@korix/openapi-swagger-ui-plugin`](./packages/openapi-swagger-ui-plugin) - Interactive API documentation with Swagger UI |
| 115 | +- [`@korix/nodejs-server`](./packages/nodejs-server) - Node.js HTTP server adapter |
| 116 | + |
| 117 | +[View all packages →](./packages) |
| 118 | + |
| 119 | +## Built With |
| 120 | + |
| 121 | +Kori is built on top of excellent open source projects: |
| 122 | + |
| 123 | +- [Hono Router](https://hono.dev/) - Fast, lightweight, and battle-tested routing engine |
| 124 | +- [Swagger UI](https://swagger.io/tools/swagger-ui/) - Interactive API documentation |
| 125 | + |
| 126 | +## License |
| 127 | + |
| 128 | +MIT |
0 commit comments