Installation

Quick Start

bun create questpie my-app
cd my-app

This scaffolds a project with the file convention layout, runtime config, and a starter collection.

Manual Setup

1. Install packages

bun add questpie @questpie/hono

For the admin panel (optional):

bun add @questpie/admin

2. Create runtime config

src/questpie/server/questpie.config.ts

import { runtimeConfig } from "questpie";

export default runtimeConfig({
	app: {
		url: process.env.APP_URL || "http://localhost:3000",
	},
	db: {
		url: process.env.DATABASE_URL || "postgres://localhost/myapp",
	},
	secret: process.env.APP_SECRET || "change-me-in-production",
});

3. Create CLI config

questpie.config.ts

export { default } from "./src/questpie/server/questpie.config";

The CLI resolves this file at the project root to find your config.

4. Create your first collection

src/questpie/server/collections/posts.ts

import { collection } from "#questpie/factories";

export default collection("posts").fields(({ f }) => ({
	title: f.text().required(),
	body: f.textarea(),
	status: f.select(["draft", "published"]),
}));

5. Run codegen

bunx questpie generate

This scans your file convention directories, discovers collections/routes/jobs, and generates:

src/questpie/server/.generated/ — app instance, types, module augmentation

6. Push schema to database

bunx questpie push

This syncs your Drizzle schema to the database without creating migration files. Use questpie migrate:generate for production migrations.

7. Start development

bun dev

With Admin Panel

To add the admin interface, install @questpie/admin and register the plugin:

src/questpie/server/questpie.config.ts

import { adminPlugin } from "@questpie/admin/plugin";
import { runtimeConfig } from "questpie";

export default runtimeConfig({
	plugins: [adminPlugin()],
	app: {
		url: process.env.APP_URL || "http://localhost:3000",
	},
	db: {
		url: process.env.DATABASE_URL,
	},
	secret: process.env.APP_SECRET,
});

Add the admin module to your modules:

src/questpie/server/modules.ts

import { adminModule } from "@questpie/admin/server";

export default [adminModule] as const;

Re-run codegen to pick up admin conventions (config/admin.ts — sidebar, dashboard, branding):

bunx questpie generate

Adapters

QUESTPIE needs an HTTP adapter to serve your API. Choose one:

Adapter	Package	Use case
Hono	`@questpie/hono`	General purpose, fast
Elysia	`@questpie/elysia`	Bun-native, validation
Next.js	`@questpie/nextjs`	Next.js API routes

API handler (Hono example)

import { createFetchHandler } from "questpie/adapters/hono";
import { app } from "#questpie";

export default createFetchHandler(app, { basePath: "/api" });

For TanStack Start, use the generic fetch handler directly — there is no adapter package:

src/routes/api/$.ts

import { createFetchHandler } from "questpie";
import { app } from "#questpie";

const handler = createFetchHandler(app, { basePath: "/api" });

export const Route = createAPIFileRoute("/api/$")({
	GET: ({ request }) => handler(request),
	POST: ({ request }) => handler(request),
	PATCH: ({ request }) => handler(request),
	DELETE: ({ request }) => handler(request),
});

Environment Variables

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`APP_URL`	Yes	Public URL of your app
`APP_SECRET`	Yes	Secret for auth sessions
`SMTP_HOST`	No	Email SMTP host
`SMTP_PORT`	No	Email SMTP port

What's Next

First App — Build a working CRUD API
Project Structure — File convention layout

On this page