create-questpie 2.0.4 → 2.1.0

package/templates/tanstack-start/CLAUDE.md

@@ -1,147 +1,39 @@
 # CLAUDE.md
 
-This is a [QUESTPIE](https://questpie.com) project scaffolded with `create-questpie`.
+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.
 
-## Quick Reference
+## Use the QUESTPIE skills
 
-| Command                          | Purpose                                        |
-| -------------------------------- | ---------------------------------------------- |
-| `bun dev`                        | Start dev server (port 3000)                   |
-| `bun build`                      | Build for production                           |
-| `bun start`                      | Start production server                        |
-| `bun questpie add <type> <name>` | Scaffold a new entity (collection, seed, etc.) |
-| `bun questpie add --list`        | List all available scaffold types              |
-| `bun run routes:generate`        | Regenerate TanStack Router route tree          |
-| `bun run questpie:generate`      | Regenerate .generated/index.ts                 |
-| `bun run scaffold:generate`      | Regenerate route tree and QUESTPIE output      |
-| `bun run scaffold:verify`        | Regenerate codegen and type-check              |
-| `bun run db:push`                | Push schema to local dev database              |
-| `bun run migrate:create`         | Generate a migration from schema diff          |
-| `bun run migrate`                | Run pending migrations                         |
-| `bun questpie seed`              | Run pending seeds                              |
-| `docker compose up -d`           | Start PostgreSQL                               |
+- **`questpie`** — collections, globals, routes, jobs, codegen, auth, business
+  logic, typed client + TanStack Query.
+- **`questpie-admin`** — admin UI: views, blocks, custom fields, branding,
+  dashboard, live preview.
 
-## Project Architecture
+Invoke skills by name (the `/skill` convention); don't work from memory.
 
-This project follows QUESTPIE's **server-first** philosophy:
+**If they aren't installed**, install them and then trim this file to a pointer:
 
-- **Server** defines WHAT (schema, validation, access, hooks, jobs)
-- **Client** defines HOW (rendering, themes, custom components)
-
-```
-src/questpie/
-  server/              ← WHAT: data contracts and behavior
-    questpie.config.ts ← App config: runtimeConfig({ db, app, ... })
-    modules.ts         ← Module dependencies (adminModule, openApiModule, etc.)
-    config/            ← Typed configuration files
-      auth.ts          ← authConfig({...}) — Better Auth options
-      admin.ts         ← adminConfig({ sidebar, dashboard, branding, locale })
-      openapi.ts       ← openApiConfig({ info, scalar })
-      app.ts           ← (optional) appConfig({ locale, access, hooks, context })
-    .generated/        ← Codegen output (app instance + App type)
-      index.ts
-    collections/       ← One file per collection (auto-discovered)
-    globals/           ← One file per global (auto-discovered)
-    routes/            ← Server routes via route() (auto-discovered)
-    jobs/              ← Background job definitions (auto-discovered)
-    blocks/            ← Block definitions (auto-discovered)
-  admin/               ← HOW: UI rendering concerns
-    admin.ts           ← Re-exports generated admin config
-    .generated/        ← Codegen output (admin client config)
-      client.ts
+```bash
+bunx skills add questpie/questpie
 ```
 
-## Key Files
-
-- **`src/questpie/server/questpie.config.ts`** — App config: `runtimeConfig({ db, app, ... })`.
-- **`src/questpie/server/modules.ts`** — Module dependencies: `export default [adminModule, openApiModule] as const`.
-- **`src/questpie/server/config/auth.ts`** — Auth config via `authConfig()` factory.
-- **`src/questpie/server/config/admin.ts`** — Admin config (sidebar, dashboard, branding, locale) via `adminConfig()` factory.
-- **`src/questpie/server/config/app.ts`** — _(optional, not scaffolded)_ App config (locale, access, hooks, context) via `appConfig()`. Create when needed.
-- **`src/questpie/server/.generated/index.ts`** — Codegen output. Exports typed `app` instance and `App` type. Run `bun run questpie:generate` to regenerate.
-- **`src/lib/env.ts`** — Type-safe env variables via `@t3-oss/env-core`. Add new env vars here with Zod schemas.
-- **`questpie.config.ts`** — CLI config (migration directory, app reference).
-- **`src/routes/api/$.ts`** — API catch-all handler. Serves REST + OpenAPI docs at `/api/docs`.
-
-## Admin User Contract
-
-`adminModule` includes the starter auth model and owns the canonical Better Auth `user` collection shape used by admin setup and login guards. That contract includes `user.role` (`admin` or `user`).
-
-Do **not** create a replacement `collection("user")` from scratch. If you need custom user fields or admin layout, merge `starterModule.collections.user` or `adminModule.collections.user` and extend it. Replacing the user collection breaks admin setup/login.
-
-## Environment Variables
-
-Defined in `src/lib/env.ts` with runtime validation. See `.env.example` for all available variables.
-
-Required:
-
-- `DATABASE_URL` — PostgreSQL connection string
-
-Optional (with defaults):
-
-- `APP_URL` — Application URL (default: `http://localhost:3000`)
-- `BETTER_AUTH_SECRET` — Auth secret key
-- `MAIL_ADAPTER` — `console` or `smtp`
-
-## Common Tasks
-
-### Add a new collection
-
-Preferred workflow:
+## Docs for LLMs
 
-1. Run `bun questpie add collection my-thing`
-2. The CLI creates the file and auto-runs codegen
-3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
+- 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)
 
-Manual workflow:
+## This project
 
-1. Create `src/questpie/server/collections/my-thing.ts` with a named export:
-   ```ts
-   import { collection } from "#questpie/factories";
-   export const myThing = collection("my-thing").fields(({ f }) => ({ ... }));
-   ```
-2. Run `bun run questpie:generate` to regenerate `.generated/index.ts`
-3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
+- **Runtime**: TanStack Start + Vite + Nitro, package manager **Bun**
+- **Database**: PostgreSQL (Drizzle ORM)
+- **Auth**: Better Auth — extend the admin `user` collection, never replace it
+- **Validation**: Zod **v4**
 
-Collections are auto-discovered by codegen — no manual registration needed.
-
-### Add a new global
-
-Preferred workflow:
-
-1. Run `bun questpie add global my-global`
-2. The CLI creates the file and auto-runs codegen
-3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
-
-Manual workflow:
-
-1. Create `src/questpie/server/globals/my-global.ts` with a named export
-2. Run `bun run questpie:generate`
-3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
-
-### Add a server route (end-to-end type-safe)
-
-1. Create `src/questpie/server/routes/my-function.ts`:
-
-   ```ts
-   import { route } from "questpie/services";
-   import { z } from "zod";
-
-   export default route()
-   	.post()
-   	.schema(z.object({ id: z.string() }))
-   	.handler(async ({ input, collections }) => {
-   		// input: typed from Zod schema; collections, db, session, etc. from AppContext
-   		return { name: "result" };
-   	});
-   ```
-
-2. Run `bun run questpie:generate` — route is auto-discovered and available at `/api/my-function`
-
-See AGENTS.md for detailed route patterns, access control, and TanStack Query integration.
-
-## Documentation
-
-- **QUESTPIE Docs**: https://questpie.com/docs
-- **Getting Started**: https://questpie.com/docs/getting-started
-- **API Reference (local)**: http://localhost:3000/api/docs (Scalar UI, available when dev server is running)
+```bash
+bun dev                              # Dev server (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/tanstack-start/README.md

@@ -12,7 +12,7 @@ A [QUESTPIE](https://questpie.com) app built with TanStack Start.
 ### Setup
 
 ```bash
-# 1) Start PostgreSQL
+# 1) Start PostgreSQL (also provisions required extensions for local dev)
 docker compose up -d
 
 # 2) Regenerate codegen and type-check
@@ -28,6 +28,18 @@ bun run dev
 - Admin panel: `http://localhost:3000/admin`
 - API docs (Scalar): `http://localhost:3000/api/docs`
 
+### 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) for details.
+
 ## Project Structure
 
 ```text

package/templates/tanstack-start/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/tanstack-start/docker-compose.yml

@@ -10,6 +10,7 @@ services:
       - "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

package/templates/tanstack-start/src/lib/auth-client.ts

@@ -1,4 +1,4 @@
-import type { AppConfig } from "@/questpie/server/app.js";
+import type { AppConfig } from "@/questpie/server/app";
 import { createAdminAuthClient } from "@questpie/admin/client";
 
 export const authClient = createAdminAuthClient<AppConfig>({

package/templates/tanstack-start/src/lib/client.ts

@@ -1,6 +1,6 @@
 import { createClient } from "questpie/client";
 
-import type { AppConfig } from "@/questpie/server/app.js";
+import type { AppConfig } from "@/questpie/server/app";
 
 export const client = createClient<AppConfig>({
 	baseURL:

package/templates/tanstack-start/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;

package/templates/tanstack-start/src/questpie/server/collections/index.ts

@@ -1 +1 @@
-export { posts } from "./posts.collection.js";
+export { posts } from "./posts.collection";

package/templates/tanstack-start/src/questpie/server/globals/index.ts

@@ -1 +1 @@
-export { siteSettings } from "./site-settings.global.js";
+export { siteSettings } from "./site-settings.global";

package/templates/tanstack-start/src/questpie/server/questpie.config.ts

@@ -9,7 +9,7 @@
 import { runtimeConfig } from "questpie/app";
 import { ConsoleAdapter } from "questpie/adapters/console";
 
-import { env } from "@/lib/env.js";
+import { env } from "@/lib/env";
 
 export default runtimeConfig({
 	app: { url: env.APP_URL },

package/templates/tanstack-start/src/routes/__root.tsx

@@ -1,4 +1,11 @@
-import { createRootRoute } from "@tanstack/react-router";
+import {
+	createRootRoute,
+	HeadContent,
+	Link,
+	Scripts,
+} from "@tanstack/react-router";
+
+import appCss from "../styles.css?url";
 
 export const Route = createRootRoute({
 	head: () => ({
@@ -7,7 +14,30 @@ export const Route = createRootRoute({
 			{ name: "viewport", content: "width=device-width, initial-scale=1" },
 			{ title: "{{projectName}}" },
 		],
+		links: [{ rel: "stylesheet", href: appCss }],
 	}),
+	notFoundComponent: () => (
+		<html lang="en">
+			<head>
+				<HeadContent />
+			</head>
+			<body className="bg-background text-foreground min-h-screen antialiased">
+				<main className="mx-auto flex min-h-screen max-w-md flex-col items-center justify-center px-6 text-center">
+					<h1 className="text-3xl font-bold tracking-tight">Page not found</h1>
+					<p className="text-muted-foreground mt-3">
+						The page you are looking for does not exist.
+					</p>
+					<Link
+						to="/"
+						className="text-primary mt-6 inline-block text-sm font-medium hover:underline"
+					>
+						Back to homepage
+					</Link>
+				</main>
+				<Scripts />
+			</body>
+		</html>
+	),
 	shellComponent: RootDocument,
 });
 

package/templates/tanstack-start/src/routes/api/$.ts

@@ -1,6 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { createFetchHandler } from "questpie/http";
-import { app } from "@/questpie/server/app.js";
+import { app } from "@/questpie/server/app";
 
 const handler = createFetchHandler(app, {
 	basePath: "/api",

package/templates/tanstack-start/src/routes/index.tsx

@@ -0,0 +1,97 @@
+import {
+	createFileRoute,
+	HeadContent,
+	Link,
+	Scripts,
+} from "@tanstack/react-router";
+
+import appCss from "@/styles.css?url";
+
+export const Route = createFileRoute("/")({
+	head: () => ({
+		title: "{{projectName}}",
+		links: [{ rel: "stylesheet", href: appCss }],
+	}),
+	component: Home,
+});
+
+function Home() {
+	return (
+		<html lang="en">
+			<head>
+				<HeadContent />
+			</head>
+			<body className="bg-background text-foreground min-h-screen antialiased">
+				<main className="mx-auto flex min-h-screen max-w-3xl flex-col items-center justify-center px-6 py-16 text-center">
+					<span className="text-muted-foreground mb-4 text-xs font-medium uppercase tracking-widest">
+						Powered by QUESTPIE
+					</span>
+					<h1 className="text-4xl font-bold tracking-tight sm:text-5xl">
+						{"{{projectName}}"}
+					</h1>
+					<p className="text-muted-foreground mt-4 text-lg">
+						Your QUESTPIE app is running. Here is where to go next.
+					</p>
+
+					<div className="mt-12 grid w-full grid-cols-1 gap-4 text-left sm:grid-cols-3">
+						<Link
+							to="/admin"
+							className="group hover:border-primary/30 block rounded-lg border p-5 transition-all hover:shadow-md"
+						>
+							<h2 className="group-hover:text-primary font-semibold transition-colors">
+								Admin panel
+							</h2>
+							<p className="text-muted-foreground mt-1 text-sm">
+								Manage your content and settings.
+							</p>
+							<span className="text-primary mt-3 inline-block text-sm font-medium">
+								Open /admin →
+							</span>
+						</Link>
+
+						<a
+							href="/api/docs"
+							className="group hover:border-primary/30 block rounded-lg border p-5 transition-all hover:shadow-md"
+						>
+							<h2 className="group-hover:text-primary font-semibold transition-colors">
+								API docs
+							</h2>
+							<p className="text-muted-foreground mt-1 text-sm">
+								Explore the REST API in Scalar.
+							</p>
+							<span className="text-primary mt-3 inline-block text-sm font-medium">
+								Open /api/docs →
+							</span>
+						</a>
+
+						<a
+							href="https://questpie.com/docs"
+							target="_blank"
+							rel="noreferrer"
+							className="group hover:border-primary/30 block rounded-lg border p-5 transition-all hover:shadow-md"
+						>
+							<h2 className="group-hover:text-primary font-semibold transition-colors">
+								Documentation
+							</h2>
+							<p className="text-muted-foreground mt-1 text-sm">
+								Learn the framework and patterns.
+							</p>
+							<span className="text-primary mt-3 inline-block text-sm font-medium">
+								questpie.com/docs →
+							</span>
+						</a>
+					</div>
+
+					<p className="text-muted-foreground mt-12 text-sm">
+						Edit{" "}
+						<code className="bg-muted rounded px-1.5 py-0.5 font-mono text-xs">
+							src/routes/index.tsx
+						</code>{" "}
+						to change this page.
+					</p>
+				</main>
+				<Scripts />
+			</body>
+		</html>
+	);
+}