Hand-Crafted Setup

If you have an existing project and want to add Quickback-generated API endpoints, you can set up the definitions directory manually instead of using a template.

Prerequisites

An existing Hono-based project (Cloudflare Workers or Bun)
Node.js 18+ or Bun installed
The Quickback CLI: npm install -g @kardoe/quickback

Setup

1. Create the Quickback Directory

Create a quickback/ directory in your project root with the following structure:

your-project/
├── quickback/
│   ├── quickback.config.ts
│   └── features/
│       └── (your features go here)
├── src/                          # Your existing code
├── package.json
└── ...

mkdir -p quickback/features

2. Write Your Config

Create quickback/quickback.config.ts:

import { defineConfig } from "@quickback/define";

export default defineConfig({
  name: "my-app",
  template: "hono",
  features: ["organizations"],
  providers: {
    runtime: { name: "cloudflare", config: {} },
    database: {
      name: "cloudflare-d1",
      config: { binding: "DB" },
    },
    auth: { name: "better-auth", config: {} },
  },
});

Adjust the providers to match your existing stack. See Providers for all options.

3. Create Your First Feature

Create a feature directory with a schema + security definition:

mkdir quickback/features/customers

Create quickback/features/customers/customers.ts:

import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
import { defineTable } from "@quickback/compiler";

export const customers = sqliteTable("customers", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  email: text("email").notNull(),
  status: text("status").default("active"),
  organizationId: text("organization_id").notNull(),
});

export default defineTable(customers, {
  firewall: {
    organization: {},
  },
  guards: {
    createable: ["name", "email", "status"],
    updatable: ["name", "email", "status"],
    immutable: ["id", "organizationId"],
  },
  masking: {
    email: { type: "email", show: { roles: ["admin"] } },
  },
  crud: {
    list: { access: { roles: ["owner", "admin", "member"] } },
    get: { access: { roles: ["owner", "admin", "member"] } },
    create: { access: { roles: ["owner", "admin"] } },
    update: { access: { roles: ["owner", "admin"] } },
    delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
  },
});

4. Log In and Compile

quickback login
quickback compile

The compiler generates a complete src/ directory with route handlers, middleware, database schemas, and migrations.

5. Integrate with Your Existing Code

The compiled output creates a self-contained Hono app in src/index.ts. If you need to integrate the generated routes into an existing Hono app, you can import the feature routes directly:

import { Hono } from "hono";
import customersRoutes from "./features/customers/routes";

const app = new Hono();

// Your existing routes
app.get("/", (c) => c.json({ status: "ok" }));

// Mount generated feature routes
app.route("/api/v1/customers", customersRoutes);

export default app;

Directory Structure

The compiler expects this structure inside quickback/:

quickback/
├── quickback.config.ts           # Required: compiler configuration
└── features/                     # Required: feature definitions
    ├── customers/
    │   ├── customers.ts          # Schema + security (defineTable)
    │   └── actions.ts            # Optional: custom actions
    ├── orders/
    │   ├── orders.ts
    │   └── actions.ts
    └── ...

Each feature directory should contain:

{name}.ts — The main definition file using defineTable() (required)
actions.ts — Custom actions using defineActions() (optional)

Adding Features

To add a new feature, create a new directory under quickback/features/ and recompile:

mkdir quickback/features/invoices
# Create invoices/invoices.ts with defineTable(...)
quickback compile

The compiler detects all features automatically — no registration needed.

Recompiling

After any change to your definitions, recompile to regenerate the output:

quickback compile

The compiler regenerates the entire src/ directory. Your definitions in quickback/ are the source of truth — never edit the generated files directly.

Warning: Don't edit files in src/ manually. They will be overwritten on the next compile. All changes should be made in your quickback/ definitions.

Next Steps

Configuration reference — All config options
Schema definitions — Define tables with defineTable()
Security pillars — Firewall, Access, Guards, Masking
Templates — Use a template for new projects instead

On this page