Getting Started

This tutorial takes you from zero to a small HTTP API backed by SQLite, running on Bun.

Prerequisites

• Bun v1.3+ — install from bun.sh.
• Optional: Node.js v18+ for some native dependencies.

Install

1. Create a project and add the kits you need:

   mkdir my-iskra-api && cd my-iskra-api
   bun init -y
   bun add @iskra-bun/core @iskra-bun/web-kit @iskra-bun/db-kit drizzle-orm

2. Define a database schema:

   src/db/schema.ts

   import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
   
   export const users = sqliteTable('users', {
       id: integer('id').primaryKey({ autoIncrement: true }),
       name: text('name').notNull(),
       email: text('email').notNull().unique(),
   });

3. Wire up the app with a web server and the database driver:

   src/main.ts

   import { App } from '@iskra-bun/core';
   import { WebPlugin, HealthCheckFeature, successResponse } from '@iskra-bun/web-kit';
   import { DbDriver } from '@iskra-bun/db-kit';
   import { Hono } from 'hono';
   import { users } from './db/schema';
   
   const db = new DbDriver();
   const router = new Hono();
   
   router.get('/api/users', (c) => {
       const all = db.db.select().from(users).all();
       return c.json(successResponse(all));
   });
   
   router.post('/api/users', async (c) => {
       const body = await c.req.json();
       db.db.insert(users).values(body).run();
       return c.json(successResponse(body), 201);
   });
   
   const app = new App({
       name: 'MyIskraApi',
       db: { driver: 'sqlite', url: 'app.db' },
   });
   
   app.register(db);
   app.register(new WebPlugin({ port: 3000, router, features: [new HealthCheckFeature()] }));
   
   app.start().catch((err) => app.logger.error({ err }, 'Failed to start'));

Run

bun run src/main.ts

Then, in another terminal:

# Create a user
curl -X POST http://localhost:3000/api/users \
  -H 'content-type: application/json' \
  -d '{"name":"Ada","email":"ada@example.com"}'

# List users
curl http://localhost:3000/api/users

# Health check
curl http://localhost:3000/health

Tip

Before the first run, create the table with the migrations workflow — see the Migrations guide. For a quick start you can also use bunx drizzle-kit push to sync the schema directly.

Test

Bun ships with a built-in test runner. Create a smoke test:

src/main.test.ts

import { describe, it, expect } from 'bun:test';
import { App } from '@iskra-bun/core';

describe('app', () => {
    it('starts and stops cleanly', async () => {
        const app = new App({ name: 'Test' });
        await app.start();
        await app.stop();
        expect(app).toBeDefined();
    });
});

Run it:

bun test

Next steps

• Learn the design model in Architecture.
• Add features (CORS, auth, rate limiting) from the Web Kit.
• Start from a template instead of scaffolding by hand.