create-questpie 2.0.4 → 2.1.0

package/templates/elysia/AGENTS.md

@@ -0,0 +1,56 @@
+# AGENTS.md
+
+Guidance for AI agents working in this [QUESTPIE](https://questpie.com) project.
+
+## Use the QUESTPIE skills
+
+This project is built on QUESTPIE. Do not work from memory — the framework is
+codegen-driven and the APIs evolve. Lean on the installed skill:
+
+- **`questpie`** — collections, globals, routes, jobs, codegen, auth, business
+  logic, the typed client + TanStack Query. Invoke it for any server/data work.
+
+Invoke skills by name (the `/skill` convention) — they are commands, not files
+to read. This is a **headless API** template (no admin UI), so the
+`questpie-admin` skill does not apply here.
+
+**If the skill is NOT installed**, install it first, then trim this file:
+
+```bash
+bunx skills add questpie/questpie
+```
+
+After installing, replace the body of this file with a one-line pointer to the
+skill above — it is the always-current source of truth and this doc should not
+duplicate it.
+
+## Docs for LLMs
+
+When the skill isn't enough, consult:
+
+- https://questpie.com/llms.txt — doc sitemap
+- https://questpie.com/llms-full.txt — full docs in one LLM-optimized file
+- http://localhost:3000/api/docs — live API reference (Scalar, dev server running)
+
+## This project
+
+- **Runtime**: Elysia on **Bun** (no bundler — the QUESTPIE `.js` ESM import
+  convention resolves natively). Package manager **Bun**.
+- **Shape**: headless API only — no admin UI, no React. The fetch handler is
+  mounted at `src/index.ts` under `/api`.
+- **Database**: PostgreSQL via Drizzle ORM (Postgres extensions are not
+  auto-created — see `README.md`)
+- **Auth**: Better Auth (email/password). The typed `better-auth/client` lives
+  in `src/lib/auth-client.ts` for a consuming frontend or scripts.
+- **Validation**: Zod **v4** (not v3)
+- **Source layout**: server contracts in `src/questpie/server/`, HTTP mount in
+  `src/index.ts`, typed client + TanStack Query in `src/lib/`
+
+## Key scripts
+
+```bash
+bun dev                     # Start dev server with watch (port 3000)
+bun run scaffold:verify     # Regenerate codegen + type-check
+bun run db:push             # Push schema to the local dev database
+bun questpie add collection <name>   # Scaffold an entity (auto-runs codegen)
+```

package/templates/elysia/CLAUDE.md

@@ -0,0 +1,39 @@
+# CLAUDE.md
+
+This is a [QUESTPIE](https://questpie.com) project. See **`AGENTS.md`** for the
+full agent guide — it is the source of truth and this file mirrors it.
+
+## Use the QUESTPIE skill
+
+- **`questpie`** — collections, globals, routes, jobs, codegen, auth, business
+  logic, typed client + TanStack Query.
+
+Invoke skills by name (the `/skill` convention); don't work from memory. This is
+a **headless API** template (no admin UI), so `questpie-admin` does not apply.
+
+**If it isn't installed**, install it and then trim this file to a pointer:
+
+```bash
+bunx skills add questpie/questpie
+```
+
+## Docs for LLMs
+
+- https://questpie.com/llms.txt — doc sitemap
+- https://questpie.com/llms-full.txt — full docs in one LLM-optimized file
+- http://localhost:3000/api/docs — live API reference (dev server running)
+
+## This project
+
+- **Runtime**: Elysia on **Bun** (no bundler — `.js` ESM imports resolve natively)
+- **Shape**: headless API — no admin UI, no React; fetch handler at `src/index.ts`
+- **Database**: PostgreSQL (Drizzle ORM)
+- **Auth**: Better Auth (email/password); typed `better-auth/client` in `src/lib/`
+- **Validation**: Zod **v4**
+
+```bash
+bun dev                              # Dev server with watch (port 3000)
+bun run scaffold:verify              # Regenerate codegen + type-check
+bun run db:push                      # Push schema to local dev DB
+bun questpie add collection <name>   # Scaffold an entity (auto-runs codegen)
+```

package/templates/elysia/Dockerfile

@@ -0,0 +1,24 @@
+FROM oven/bun:1.3-alpine AS base
+
+WORKDIR /app
+
+# Install dependencies
+FROM base AS deps
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+
+# Build application (bundles the entry to dist/ with the Bun target)
+FROM base AS builder
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN bun run scaffold:generate
+RUN bun run build
+
+# Production image
+FROM base AS runner
+ENV NODE_ENV=production
+ENV PORT=3000
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./package.json
+EXPOSE 3000
+CMD ["bun", "run", "dist/index.js"]

package/templates/elysia/README.md

@@ -0,0 +1,148 @@
+# {{projectName}}
+
+A [QUESTPIE](https://questpie.com) **headless API** built with [Elysia](https://elysiajs.com),
+running on [Bun](https://bun.sh). No admin UI, no React — just a typed REST API
+with Scalar docs and a typed client you can consume from any frontend.
+
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) v1.3+
+- [Docker](https://docker.com) (for local PostgreSQL)
+
+### Setup
+
+```bash
+# 1) Start PostgreSQL (also provisions required extensions for local dev)
+docker compose up -d
+
+# 2) Regenerate codegen and type-check
+bun run scaffold:verify
+
+# 3) Create local database tables
+bun run db:push
+
+# 4) Start the development server (watch mode)
+bun dev
+```
+
+- API docs (Scalar): `http://localhost:3000/api/docs` (the root `/` redirects here)
+- REST API: `http://localhost:3000/api/*`
+
+## What you get
+
+- **Headless REST API** — every collection and global is exposed under `/api`.
+- **Scalar API reference** at `/api/docs` (the `openapi` module).
+- **Auth** — Better Auth (email/password) mounted at `/api/auth`.
+- **Typed client + TanStack Query** in `src/lib/` — `client.ts`
+  (`createClient<AppConfig>`), `query.ts` (`createQuestpieQueryOptions`), and
+  `auth-client.ts` (`better-auth/client`). A separate frontend or scripts import
+  these for end-to-end type safety against your server schema.
+
+## Running on Node instead of Bun
+
+The entry (`src/index.ts`) calls `.listen()`, which serves on Bun directly. To
+run on Node, install `@elysiajs/node` and pass its adapter:
+
+```ts
+import { node } from "@elysiajs/node";
+new Elysia({ adapter: node() }) /* …routes… */ .listen(env.PORT ?? 3000);
+```
+
+## Database extensions
+
+QUESTPIE is drizzle-native and does **not** auto-create Postgres extensions. The
+starter's full-text search relies on `pg_trgm` (trigram matching).
+
+- **Local dev:** `docker compose up` provisions `pg_trgm` via
+  `docker/init-extensions.sql`, mounted into the postgres container's
+  `/docker-entrypoint-initdb.d/` and run once on first cluster init — so
+  `db:push` works out of the box.
+- **Managed Postgres:** enable required extensions through your provider before
+  deploying. See [the QUESTPIE docs](https://questpie.com/docs/deployment) for details.
+
+## Project Structure
+
+```text
+src/
+  index.ts                           # Elysia entry — mounts the fetch handler at /api
+  questpie/
+    server/
+      questpie.config.ts             # Runtime config
+      modules.ts                     # Module list (openapi/...)
+      config/
+        auth.ts                      # Auth config
+        openapi.ts                   # OpenAPI/Scalar config
+      app.ts                         # Re-export of generated app
+      .generated/                    # Codegen output (do not edit manually)
+      collections/
+        posts.collection.ts
+      globals/
+        site-settings.global.ts
+  lib/
+    env.ts
+    client.ts                        # Typed REST client (createClient<AppConfig>)
+    auth-client.ts                   # Typed Better Auth client
+    query.ts                         # TanStack Query option builders
+    query-client.ts
+migrations/
+```
+
+## Scripts
+
+| Command                          | Description                                   |
+| -------------------------------- | --------------------------------------------- |
+| `bun dev`                        | Start development server (watch)              |
+| `bun run build`                  | Bundle the entry to `dist/`                   |
+| `bun run start`                  | Run the server (no watch)                     |
+| `bun run check-types`            | Type check                                    |
+| `bun run scaffold:generate`      | Regenerate QUESTPIE codegen                   |
+| `bun run scaffold:verify`        | Regenerate codegen and type-check             |
+| `bun run questpie:generate`      | Regenerate `src/questpie/server/.generated/*` |
+| `bun questpie add <type> <name>` | Scaffold entity files (auto-runs codegen)     |
+| `bun run db:push`                | Push schema directly to local dev database    |
+| `bun run migrate`                | Run migrations                                |
+| `bun run migrate:create`         | Create migration                              |
+
+## Learn more
+
+- [Quickstart](https://questpie.com/docs/quickstart)
+- [Data modeling](https://questpie.com/docs/data-modeling)
+- [Auth](https://questpie.com/docs/auth)
+- [TanStack Query](https://questpie.com/docs/tanstack-query)
+- [Deployment](https://questpie.com/docs/deployment)
+
+## Adding a Collection
+
+Preferred workflow:
+
+1. Run `bun questpie add collection products`.
+2. The CLI creates the file and runs codegen automatically.
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
+
+Manual workflow (when you create files by hand):
+
+1. Create a file in `src/questpie/server/collections/`.
+2. Export a collection builder from that file.
+3. Run `bun run questpie:generate`.
+4. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
+
+Collections are discovered automatically by codegen. No manual `app.ts` registration is required.
+
+## Adding a Global
+
+Preferred workflow:
+
+1. Run `bun questpie add global marketing`.
+2. The CLI creates the file and runs codegen automatically.
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
+
+Manual workflow (when you create files by hand):
+
+1. Create a file in `src/questpie/server/globals/`.
+2. Export a global builder from that file.
+3. Run `bun run questpie:generate`.
+4. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
+
+Globals are discovered automatically by codegen. No manual `app.ts` registration is required.

package/templates/elysia/docker/init-extensions.sql

@@ -0,0 +1,11 @@
+-- Postgres extensions provisioned for local development.
+-- Mounted into the postgres container at /docker-entrypoint-initdb.d/ and run
+-- once, on first cluster init, before the app connects.
+--
+-- QUESTPIE is drizzle-native: the app does NOT auto-create extensions. The
+-- starter's full-text search uses pg_trgm (trigram matching), so we provision
+-- it here to keep `db:push` working out-of-the-box while you prototype.
+--
+-- On managed Postgres, enable required extensions via your provider instead.
+-- See https://questpie.com/docs for details.
+CREATE EXTENSION IF NOT EXISTS "pg_trgm";

package/templates/elysia/docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  postgres:
+    image: postgres:17
+    container_name: {{projectName}}-postgres
+    environment:
+      POSTGRES_DB: {{databaseName}}
+      POSTGRES_USER: {{databaseUser}}
+      POSTGRES_PASSWORD: {{databasePassword}}
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./docker/init-extensions.sql:/docker-entrypoint-initdb.d/init-extensions.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {{databaseUser}}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:

package/templates/elysia/env.example

@@ -0,0 +1,16 @@
+# Database
+DATABASE_URL=postgresql://{{databaseUser}}:{{databasePassword}}@localhost:5432/{{databaseName}}
+
+# Application
+APP_URL=http://localhost:3000
+PORT=3000
+
+# Auth (Better Auth)
+BETTER_AUTH_SECRET={{authSecret}}
+
+# Email Adapter (console | smtp)
+MAIL_ADAPTER=console
+
+# SMTP (if using smtp adapter)
+# SMTP_HOST=localhost
+# SMTP_PORT=1025

package/templates/elysia/gitignore

@@ -0,0 +1,6 @@
+node_modules
+.DS_Store
+dist
+*.local
+.env
+uploads

package/templates/elysia/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "{{projectName}}",
+	"version": "0.0.1",
+	"private": true,
+	"type": "module",
+	"imports": {
+		"#questpie": "./src/questpie/server/.generated/index.ts",
+		"#questpie/*": "./src/questpie/server/.generated/*"
+	},
+	"scripts": {
+		"dev": "bun --watch src/index.ts",
+		"start": "bun run src/index.ts",
+		"build": "bun build src/index.ts --target=bun --outdir=dist",
+		"check-types": "tsc --noEmit",
+		"questpie:generate": "questpie generate -c src/questpie/server/questpie.config.ts",
+		"scaffold:generate": "bun run questpie:generate",
+		"db:push": "questpie push -c questpie.config.ts",
+		"migrate": "questpie migrate -c questpie.config.ts",
+		"migrate:create": "questpie migrate:create -c questpie.config.ts",
+		"migrate:status": "questpie migrate:status -c questpie.config.ts",
+		"migrate:down": "questpie migrate:down -c questpie.config.ts",
+		"migrate:reset": "questpie migrate:reset -c questpie.config.ts",
+		"migrate:fresh": "questpie migrate:fresh -c questpie.config.ts",
+		"scaffold:verify": "bun run scaffold:generate && bun run check-types"
+	},
+	"dependencies": {
+		"@electric-sql/pglite": "^0.3.14",
+		"@questpie/openapi": "latest",
+		"@questpie/tanstack-query": "latest",
+		"@t3-oss/env-core": "^0.12.0",
+		"@tanstack/react-query": "^5.62.11",
+		"better-auth": "^1.6.11",
+		"drizzle-orm": "1.0.0-beta.6-4414a19",
+		"elysia": "^1.4.29",
+		"nodemailer": "^7.0.12",
+		"pg": "^8.13.1",
+		"pg-boss": "^12.5.4",
+		"questpie": "latest",
+		"zod": "^4.2.1"
+	},
+	"devDependencies": {
+		"@types/pg": "^8.11.10",
+		"bun-types": "latest",
+		"drizzle-kit": "1.0.0-beta.6-4414a19",
+		"typescript": "^5.9.2"
+	}
+}

package/templates/elysia/questpie.config.ts

@@ -0,0 +1,12 @@
+import { app } from "@/questpie/server/app";
+
+export const config = {
+	app: app,
+	cli: {
+		migrations: {
+			directory: "./src/migrations",
+		},
+	},
+};
+
+export default config;

package/templates/elysia/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Elysia entrypoint (headless QUESTPIE API).
+ *
+ * Mounts the framework-agnostic fetch handler under `/api` and redirects the
+ * root to the Scalar API reference. Elysia runs on Bun and begins serving as
+ * soon as `.listen()` is called — `bun run src/index.ts` boots the server.
+ */
+import { Elysia } from "elysia";
+import { createFetchHandler } from "questpie/http";
+
+import { env } from "@/lib/env";
+import { app as questpie } from "@/questpie/server/app";
+
+const handler = createFetchHandler(questpie, { basePath: "/api" });
+
+new Elysia()
+	.all("/api/*", async ({ request }) => (await handler(request)) ?? new Response("Not Found", { status: 404 }))
+	.get("/", () => new Response(null, { status: 302, headers: { Location: "/api/docs" } }))
+	.listen(env.PORT ?? 3000);
+
+console.log(`🚀 QUESTPIE headless API on http://localhost:${env.PORT ?? 3000}`);

package/templates/elysia/src/lib/auth-client.ts

@@ -0,0 +1,32 @@
+import type { BetterAuthOptions } from "better-auth";
+import { createAuthClient } from "better-auth/client";
+
+import type { AppConfig } from "@/questpie/server/app";
+
+/**
+ * Type-safe Better Auth client (vanilla, no React).
+ *
+ * `signIn`, `signUp`, `signOut`, `getSession`, etc. are fully typed from the
+ * app's auth configuration via `AppConfig["auth"]`. This headless template
+ * ships the framework-agnostic `better-auth/client` so a separate frontend or
+ * scripts can consume it.
+ */
+type AppAuthOptions = AppConfig["auth"] extends BetterAuthOptions
+	? AppConfig["auth"]
+	: BetterAuthOptions;
+
+type AuthClientOptions = {
+	baseURL: string;
+	fetchOptions?: { credentials?: RequestCredentials };
+	$InferAuth: AppAuthOptions;
+};
+
+export const authClient = createAuthClient<AuthClientOptions>({
+	baseURL:
+		typeof window !== "undefined"
+			? `${window.location.origin}/api/auth`
+			: `${process.env.APP_URL || "http://localhost:3000"}/api/auth`,
+	fetchOptions: { credentials: "include" },
+} as AuthClientOptions);
+
+export type AuthClient = typeof authClient;

package/templates/elysia/src/lib/client.ts

@@ -0,0 +1,13 @@
+import { createClient } from "questpie/client";
+
+import type { AppConfig } from "@/questpie/server/app";
+
+export const client = createClient<AppConfig>({
+	baseURL:
+		typeof window !== "undefined"
+			? window.location.origin
+			: process.env.APP_URL || "http://localhost:3000",
+	basePath: "/api",
+});
+
+export type AppClient = typeof client;

package/templates/elysia/src/lib/env.ts

@@ -0,0 +1,24 @@
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+
+export const env = createEnv({
+	server: {
+		DATABASE_URL: z.string().url(),
+		APP_URL: z.string().url().default("http://localhost:3000"),
+		PORT: z
+			.string()
+			.transform(Number)
+			.pipe(z.number().int().positive())
+			.default(3000),
+		BETTER_AUTH_SECRET: z.string().min(1).default("change-me-in-production"),
+		MAIL_ADAPTER: z.enum(["console", "smtp"]).default("console"),
+		SMTP_HOST: z.string().optional(),
+		SMTP_PORT: z
+			.string()
+			.transform(Number)
+			.pipe(z.number().int().positive())
+			.optional(),
+	},
+	runtimeEnv: process.env,
+	emptyStringAsUndefined: true,
+});

package/templates/elysia/src/lib/query-client.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from "@tanstack/react-query";
+
+const ONE_MINUTE = 60 * 1000;
+const FIVE_MINUTES = 5 * ONE_MINUTE;
+
+export const queryClient = new QueryClient({
+	defaultOptions: {
+		queries: {
+			staleTime: ONE_MINUTE,
+			gcTime: FIVE_MINUTES,
+			refetchOnWindowFocus: false,
+			retry: 1,
+		},
+		mutations: {
+			retry: 0,
+		},
+	},
+});

package/templates/elysia/src/lib/query.ts

@@ -0,0 +1,18 @@
+import { createQuestpieQueryOptions } from "@questpie/tanstack-query";
+
+import { client } from "@/lib/client";
+
+/**
+ * Typed TanStack Query option builders for this project.
+ *
+ * `q.collections.*`, `q.globals.*`, and `q.routes.*` return `queryOptions()` /
+ * `mutationOptions()` objects you pass straight into `useQuery` / `useMutation`.
+ * Full type inference flows from the server schema via `AppConfig`.
+ *
+ * @example
+ * const { data } = useQuery(q.collections.posts.find({ limit: 10 }));
+ * const create = useMutation(q.collections.posts.create());
+ */
+export const q = createQuestpieQueryOptions(client);
+
+export type QueryOptions = typeof q;