create-questpie 1.0.0 → 2.0.1

package/templates/tanstack-start/CLAUDE.md

@@ -1,54 +1,74 @@
 # CLAUDE.md
 
-This is a [QUESTPIE CMS](https://questpie.com) project scaffolded with `create-questpie`.
+This is a [QUESTPIE](https://questpie.com) project scaffolded with `create-questpie`.
 
 ## Quick Reference
 
-| Command                       | Purpose                      |
-| ----------------------------- | ---------------------------- |
-| `bun dev`                     | Start dev server (port 3000) |
-| `bun build`                   | Build for production         |
-| `bun start`                   | Start production server      |
-| `bun questpie migrate`        | Run database migrations      |
-| `bun questpie migrate:create` | Generate a new migration     |
-| `docker compose up -d`        | Start PostgreSQL             |
+| 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 questpie generate`          | Regenerate .generated/index.ts                 |
+| `bun questpie migrate:create`    | Generate a migration from schema diff          |
+| `bun questpie migrate`           | Run pending migrations                         |
+| `bun questpie seed`              | Run pending seeds                              |
+| `docker compose up -d`           | Start PostgreSQL                               |
 
 ## Project Architecture
 
 This project follows QUESTPIE's **server-first** philosophy:
+
 - **Server** defines WHAT (schema, validation, access, hooks, jobs)
 - **Client** defines HOW (rendering, themes, custom components)
 
 ```
 src/questpie/
-  server/           ← WHAT: data contracts and behavior
-    app.ts          ← Main composition root (collections, globals, auth, build)
-    builder.ts      ← Shared builder: qb = q.use(adminModule)
-    rpc.ts          ← RPC router instance
-    sidebar.ts      ← Admin sidebar configuration
-    dashboard.ts    ← Admin dashboard configuration
-    collections/    ← One file per collection (*.collection.ts)
-    globals/        ← One file per global (*.global.ts)
-  admin/            ← HOW: UI rendering concerns
-    admin.ts        ← Client builder: qa<AppCMS>().use(adminModule)
-    builder.ts      ← Client-side builder instance
+  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
 ```
 
 ## Key Files
 
-- **`src/questpie/server/app.ts`** — The composition root. Register collections, globals, sidebar, dashboard, auth, and call `.build()`.
+- **`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 `bunx 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/cms/$.ts`** — CMS API catch-all handler. Serves REST + OpenAPI docs at `/api/cms/docs`.
+- **`src/routes/api/$.ts`** — API catch-all handler. Serves REST + OpenAPI docs at `/api/docs`.
 
 ## 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`
@@ -57,49 +77,61 @@ Optional (with defaults):
 
 ### Add a new collection
 
-1. Create `src/questpie/server/collections/my-thing.collection.ts`
-2. Export from `src/questpie/server/collections/index.ts`
-3. Register in `src/questpie/server/app.ts` → `.collections({ posts, myThing })`
-4. Add to sidebar in `src/questpie/server/sidebar.ts`
-5. Run `bun questpie migrate:create` to generate migration
+Preferred workflow:
+
+1. Run `bun questpie add collection my-thing`
+2. The CLI creates the file and auto-runs codegen
+3. Run `bun questpie migrate:create`
+
+Manual workflow:
+
+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 `bunx questpie generate` to regenerate `.generated/index.ts`
+3. Run `bun questpie migrate:create` to generate migration
+
+Collections are auto-discovered by codegen — no manual registration needed.
 
 ### Add a new global
 
-1. Create `src/questpie/server/globals/my-global.global.ts`
-2. Export from `src/questpie/server/globals/index.ts`
-3. Register in `src/questpie/server/app.ts` → `.globals({ siteSettings, myGlobal })`
-4. Add to sidebar in `src/questpie/server/sidebar.ts`
-5. Run `bun questpie migrate:create`
+Preferred workflow:
+
+1. Run `bun questpie add global my-global`
+2. The CLI creates the file and auto-runs codegen
+3. Run `bun questpie migrate:create`
+
+Manual workflow:
+
+1. Create `src/questpie/server/globals/my-global.ts` with a named export
+2. Run `bunx questpie generate`
+3. Run `bun questpie migrate:create`
 
-### Add an RPC function (end-to-end type-safe)
+### Add a server route (end-to-end type-safe)
 
-`rpc.ts` uses `rpc<AppCMS>()` — a type-only import from `app.ts` (erased at runtime, no circular dependency). This gives you fully typed `app` in all handlers.
+1. Create `src/questpie/server/routes/my-function.ts`:
 
-1. Create `src/questpie/server/functions/my-function.ts`:
    ```ts
-   import { r } from "@/questpie/server/rpc";
+   import { route } from "questpie";
    import { z } from "zod";
 
-   export const myFunction = r.fn({
-     schema: z.object({ id: z.string() }),
-     handler: async ({ input, app }) => {
-       // input: { id: string } — typed from Zod schema
-       // app: AppCMS — fully typed, autocomplete works
-       return { name: "result" };
-     },
-   });
-   ```
-2. Register in `app.ts` → `appRpc = r.router({ ...adminRpc, myFunction })`
-3. Call from client (fully typed):
-   ```ts
-   const result = await client.rpc.myFunction({ id: "123" });
-   // result: { name: string } — inferred from handler return type
+   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" };
+   	});
    ```
 
-See AGENTS.md for detailed RPC type flow, access control, and TanStack Query integration.
+2. Run `bunx 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/cms/docs (Scalar UI, available when dev server is running)
+- **API Reference (local)**: http://localhost:3000/api/docs (Scalar UI, available when dev server is running)

package/templates/tanstack-start/README.md

@@ -1,94 +1,107 @@
 # {{projectName}}
 
-A [QUESTPIE CMS](https://questpie.com) project built with TanStack Start.
+A [QUESTPIE](https://questpie.com) app built with TanStack Start.
 
-## Getting Started
+## Quick Start
 
 ### Prerequisites
 
-- [Bun](https://bun.sh) (v1.3+)
-- [Docker](https://docker.com) (for PostgreSQL)
+- [Bun](https://bun.sh) v1.3+
+- [Docker](https://docker.com) (for local PostgreSQL)
 
 ### Setup
 
 ```bash
-# Start PostgreSQL
+# 1) Start PostgreSQL
 docker compose up -d
 
-# Run database migrations
+# 2) Run migrations
 bun questpie migrate
 
-# Start the dev server
+# 3) Start development server
 bun dev
 ```
 
-The admin panel will be available at [http://localhost:3000/admin](http://localhost:3000/admin).
-
-The API docs (Scalar UI) are at [http://localhost:3000/api/cms/docs](http://localhost:3000/api/cms/docs).
+- Admin panel: `http://localhost:3000/admin`
+- API docs (Scalar): `http://localhost:3000/api/docs`
 
 ## Project Structure
 
-```
+```text
 src/
   questpie/
     server/
-      app.ts                        # Main CMS configuration
-      builder.ts                    # Server-side builder
-      rpc.ts                        # RPC router
+      questpie.config.ts             # Runtime config
+      modules.ts                     # Module list (admin/openapi/...)
+      config/
+        admin.ts                     # Admin sidebar/dashboard/branding
+        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         # Posts collection
+        posts.collection.ts
       globals/
-        site-settings.global.ts     # Site settings
+        site-settings.global.ts
     admin/
-      admin.ts                      # Admin UI configuration
-      builder.ts                    # Client-side builder
+      admin.ts                       # Re-export of generated admin config
+      modules.ts                     # Admin client module defaults
+      .generated/                    # Admin client codegen output
   routes/
-    admin.tsx                       # Admin layout
-    admin/                          # Admin routes
-    api/cms/$.ts                    # CMS API handler
+    api/$.ts                         # QUESTPIE fetch handler mount
+    admin.tsx
+    admin/
   lib/
-    env.ts                          # Type-safe environment variables
-    cms-client.ts                   # CMS API client
-    auth-client.ts                  # Auth client
-    query-client.ts                 # React Query client
-  migrations/                       # Database migrations
+    env.ts
+    client.ts
+    auth-client.ts
+    query-client.ts
+migrations/
 ```
 
 ## Scripts
 
-| Command                       | Description              |
-| ----------------------------- | ------------------------ |
-| `bun dev`                     | Start development server |
-| `bun build`                   | Build for production     |
-| `bun start`                   | Start production server  |
-| `bun questpie migrate`        | Run database migrations  |
-| `bun questpie migrate:create` | Create a new migration   |
+| Command                          | Description                                   |
+| -------------------------------- | --------------------------------------------- |
+| `bun dev`                        | Start development server                      |
+| `bun build`                      | Build for production                          |
+| `bun start`                      | Start production server                       |
+| `bun check-types`                | Type check                                    |
+| `bun questpie add <type> <name>` | Scaffold entity files (auto-runs codegen)     |
+| `bun questpie migrate`           | Run migrations                                |
+| `bun questpie migrate:create`    | Create migration                              |
+| `bunx questpie generate`         | Regenerate `src/questpie/server/.generated/*` |
 
-## Adding Collections
+## Adding a Collection
 
-Create a new file following the naming convention:
+Preferred workflow:
 
-```
-src/questpie/server/collections/my-collection.collection.ts
-```
+1. Run `bun questpie add collection products`.
+2. The CLI creates the file and runs codegen automatically.
+3. Run `bun questpie migrate:create`.
 
-Then register it in `app.ts`:
+Manual workflow (when you create files by hand):
 
-```ts
-import { myCollection } from "./collections/my-collection.collection.js";
+1. Create a file in `src/questpie/server/collections/`.
+2. Export a collection builder from that file.
+3. Run `bunx questpie generate`.
+4. Run `bun questpie migrate:create`.
 
-// Add to .collections()
-.collections({ posts, myCollection })
-```
+Collections are discovered automatically by codegen. No manual `app.ts` registration is required.
 
-## Adding Globals
+## Adding a Global
 
-```
-src/questpie/server/globals/my-global.global.ts
-```
+Preferred workflow:
 
-Then register in `app.ts`:
+1. Run `bun questpie add global marketing`.
+2. The CLI creates the file and runs codegen automatically.
+3. Run `bun questpie migrate:create`.
 
-```ts
-.globals({ siteSettings, myGlobal })
-```
+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 `bunx questpie generate`.
+4. Run `bun questpie migrate:create`.
+
+Globals are discovered automatically by codegen. No manual `app.ts` registration is required.

package/templates/tanstack-start/components.json

@@ -1,22 +1,22 @@
 {
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "base-lyra",
-  "rsc": false,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "src/styles.css",
-    "baseColor": "neutral",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "iconLibrary": "hugeicons",
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "registries": {}
+	"$schema": "https://ui.shadcn.com/schema.json",
+	"style": "base-lyra",
+	"rsc": false,
+	"tsx": true,
+	"tailwind": {
+		"config": "",
+		"css": "src/styles.css",
+		"baseColor": "neutral",
+		"cssVariables": true,
+		"prefix": ""
+	},
+	"iconLibrary": "hugeicons",
+	"aliases": {
+		"components": "@/components",
+		"utils": "@/lib/utils",
+		"ui": "@/components/ui",
+		"lib": "@/lib",
+		"hooks": "@/hooks"
+	},
+	"registries": {}
 }

package/templates/tanstack-start/package.json

@@ -3,6 +3,10 @@
 	"version": "0.0.1",
 	"private": true,
 	"type": "module",
+	"imports": {
+		"#questpie": "./src/questpie/server/.generated/index.ts",
+		"#questpie/*": "./src/questpie/server/.generated/*"
+	},
 	"scripts": {
 		"dev": "bun --bun vite dev --port 3000",
 		"build": "vite build",
@@ -24,6 +28,8 @@
 		"zod": "^4.2.1"
 	},
 	"devDependencies": {
+		"@iconify/json": ">=2",
+		"@questpie/vite-plugin-iconify": "latest",
 		"@tailwindcss/vite": "^4.0.0",
 		"@tanstack/devtools-vite": "latest",
 		"@tanstack/react-devtools": "latest",

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

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

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

@@ -1,12 +1,12 @@
+import type { AppConfig } from "@/questpie/server/app.js";
 import { createAdminAuthClient } from "@questpie/admin/client";
-import type { AppCMS } from "@/questpie/server/app.js";
 
-export const authClient = createAdminAuthClient<AppCMS>({
+export const authClient = createAdminAuthClient<AppConfig>({
 	baseURL:
 		typeof window !== "undefined"
 			? window.location.origin
 			: process.env.APP_URL || "http://localhost:3000",
-	basePath: "/api/cms/auth",
+	basePath: "/api/auth",
 });
 
 export type AuthClient = typeof authClient;

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

@@ -0,0 +1,13 @@
+import { createClient } from "questpie/client";
+
+import type { AppConfig } from "@/questpie/server/app.js";
+
+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/tanstack-start/src/lib/env.ts

@@ -2,26 +2,23 @@ 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,
+	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/tanstack-start/src/lib/query-client.ts

@@ -1,9 +1,9 @@
 import { QueryClient } from "@tanstack/react-query";
 
 export const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 60 * 1000,
-    },
-  },
+	defaultOptions: {
+		queries: {
+			staleTime: 60 * 1000,
+		},
+	},
 });

package/templates/tanstack-start/src/questpie/admin/.generated/client.ts

@@ -0,0 +1,13 @@
+/**
+ * Admin Client Config
+ *
+ * Auto-generated by questpie codegen — do not edit.
+ *
+ * Pass this directly to <AdminLayoutProvider admin={admin} />
+ */
+
+import { default as _modules } from "../modules";
+
+const admin = _modules;
+
+export default admin;

package/templates/tanstack-start/src/questpie/admin/admin.ts

@@ -1,5 +1,9 @@
-import { builder } from "./builder.js";
+/**
+ * Admin Configuration
+ *
+ * Re-exports the generated admin config.
+ * Import directly from "./.generated/client" in new code.
+ */
+export { default as admin } from "./.generated/client";
 
-export const admin = builder;
-
-export type AdminConfig = typeof admin;
+export type AdminConfig = typeof import("./.generated/client").default;

package/templates/tanstack-start/src/questpie/admin/modules.ts

@@ -0,0 +1 @@
+export { default } from "@questpie/admin/client-module";