create-questpie 2.0.3 → 2.1.0

package/templates/next/AGENTS.md

@@ -0,0 +1,55 @@
+# 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 skills:
+
+- **`questpie`** — collections, globals, routes, jobs, codegen, auth, business
+  logic, the typed client + TanStack Query. Invoke it for any server/data work.
+- **`questpie-admin`** — admin UI: views, blocks, custom fields, branding,
+  dashboard, live preview. Invoke it for any admin panel work.
+
+Invoke skills by name (the `/skill` convention) — they are commands, not files
+to read.
+
+**If those skills are NOT installed**, install them 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
+skills above — they are the always-current source of truth and this doc should
+not duplicate them.
+
+## Docs for LLMs
+
+When a 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**: Next.js (App Router) + React, package manager **Bun**
+- **Database**: PostgreSQL via Drizzle ORM (Postgres extensions are not
+  auto-created — see `README.md`)
+- **Auth**: Better Auth (email/password); the `user` collection ships with
+  admin — extend it, never replace it
+- **Validation**: Zod **v4** (not v3)
+- **Source layout**: server contracts in `src/questpie/server/`, admin UI in
+  `src/questpie/admin/`, HTTP mount in `src/app/api/[...all]/route.ts`, admin
+  mount in `src/app/admin/`, typed client in `src/lib/`
+
+## Key scripts
+
+```bash
+bun dev                     # Start dev server (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/next/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 skills
+
+- **`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.
+
+Invoke skills by name (the `/skill` convention); don't work from memory.
+
+**If they aren't installed**, install them 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**: Next.js (App Router) + React, package manager **Bun**
+- **Database**: PostgreSQL (Drizzle ORM)
+- **Auth**: Better Auth — extend the admin `user` collection, never replace it
+- **Validation**: Zod **v4**
+
+```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/next/Dockerfile

@@ -0,0 +1,25 @@
+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
+FROM base AS builder
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN bun run build
+
+# Production image
+FROM base AS runner
+ENV NODE_ENV=production
+ENV PORT=3000
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+EXPOSE 3000
+CMD ["bun", "run", "start"]

package/templates/next/README.md

@@ -0,0 +1,148 @@
+# {{projectName}}
+
+A [QUESTPIE](https://questpie.com) app built with Next.js (App Router).
+
+## 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 development server
+bun run dev
+```
+
+- Admin panel: `http://localhost:3000/admin`
+- API docs (Scalar): `http://localhost:3000/api/docs`
+
+## What you get
+
+- A typed **admin panel** at `/admin` (views, dashboard, auth, media).
+- A REST API with interactive **Scalar docs** at `/api/docs`.
+- A fully **typed client** (`src/lib/client.ts`) plus TanStack Query option
+  builders (`src/lib/query.ts`) — full inference from your server schema.
+
+## Documentation
+
+- [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)
+
+### 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
+src/
+  app/
+    layout.tsx                       # Root layout + providers
+    providers.tsx                    # QueryClientProvider
+    page.tsx                         # Landing page
+    not-found.tsx                    # 404 page
+    api/
+      [...all]/route.ts              # QUESTPIE fetch handler mount
+    admin/
+      layout.tsx                     # AdminLayoutProvider (Next adapter)
+      admin.css                      # Admin Tailwind entry
+      [[...all]]/page.tsx            # Admin router + login
+  questpie/
+    server/
+      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
+      globals/
+        site-settings.global.ts
+    admin/
+      admin.ts                       # Re-export of generated admin config
+      modules.ts                     # Admin client module defaults
+      .generated/                    # Admin client codegen output
+  lib/
+    env.ts
+    client.ts
+    auth-client.ts
+    query-client.ts
+    query.ts
+migrations/
+```
+
+## Scripts
+
+| Command                          | Description                                   |
+| -------------------------------- | --------------------------------------------- |
+| `bun dev`                        | Start development server                      |
+| `bun build`                      | Build for production                          |
+| `bun start`                      | Start production server                       |
+| `bun 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                              |
+
+## 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/next/components.json

@@ -0,0 +1,22 @@
+{
+	"$schema": "https://ui.shadcn.com/schema.json",
+	"style": "base-lyra",
+	"rsc": true,
+	"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/next/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/next/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/next/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/next/gitignore

@@ -0,0 +1,10 @@
+node_modules
+.DS_Store
+dist
+*.local
+.env
+.next
+out
+next-env.d.ts
+*.tsbuildinfo
+uploads

package/templates/next/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/next/next.config.ts

@@ -0,0 +1,20 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+	// QUESTPIE is a server framework: its server graph pulls in optional native
+	// deps (the S3 storage adapter's @aws-sdk/*, only needed if you use S3) and a
+	// dynamic `import()` in the code-execution adapter. Turbopack bundles route
+	// handlers eagerly and would choke on those, so the server-only packages must
+	// run via native Node `require` instead of being bundled.
+	serverExternalPackages: [
+		"questpie",
+		"@questpie/openapi",
+		"drizzle-kit",
+		"@aws-sdk/client-s3",
+		"bun",
+		"pino",
+		"pino-pretty",
+	],
+};
+
+export default nextConfig;

package/templates/next/package.json

@@ -0,0 +1,54 @@
+{
+	"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": "next dev --turbopack --port 3000",
+		"build": "next build --turbopack",
+		"start": "next start --port 3000",
+		"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 && tsc --noEmit"
+	},
+	"dependencies": {
+		"@electric-sql/pglite": "^0.3.14",
+		"@questpie/admin": "latest",
+		"@questpie/openapi": "latest",
+		"@questpie/tanstack-query": "latest",
+		"@t3-oss/env-core": "^0.12.0",
+		"@tanstack/react-query": "^5.62.11",
+		"drizzle-orm": "1.0.0-beta.6-4414a19",
+		"next": "^16.2.9",
+		"nodemailer": "^7.0.12",
+		"pg": "^8.13.1",
+		"pg-boss": "^12.5.4",
+		"questpie": "latest",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0",
+		"shadcn": "^3.6.1",
+		"zod": "^4.2.1"
+	},
+	"devDependencies": {
+		"@tailwindcss/postcss": "^4.0.0",
+		"@types/node": "^22.0.0",
+		"@types/react": "^19.2.0",
+		"@types/react-dom": "^19.2.0",
+		"drizzle-kit": "1.0.0-beta.6-4414a19",
+		"tailwindcss": "^4.0.0",
+		"tw-animate-css": "^1.0.0",
+		"typescript": "^5.9.2"
+	}
+}

package/templates/next/postcss.config.mjs

@@ -0,0 +1,8 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+	plugins: {
+		"@tailwindcss/postcss": {},
+	},
+};
+
+export default config;

package/templates/next/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/next/src/app/admin/[[...all]]/page.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { useParams, useRouter } from "next/navigation";
+import { useCallback } from "react";
+
+import { AdminRouter, LoginPage } from "@questpie/admin/client";
+
+export default function AdminCatchAll() {
+	const router = useRouter();
+	const params = useParams<{ all?: string[] }>();
+	const segments = params.all ?? [];
+
+	const navigate = useCallback(
+		(path: string) => {
+			router.push(path);
+		},
+		[router],
+	);
+
+	if (segments[0] === "login") {
+		return (
+			<LoginPage
+				title="Welcome back"
+				description="Sign in to access admin panel"
+				showForgotPassword={false}
+				showSignUp={false}
+			/>
+		);
+	}
+
+	return (
+		<AdminRouter segments={segments} navigate={navigate} basePath="/admin" />
+	);
+}

package/templates/next/src/app/admin/admin.css

@@ -0,0 +1,4 @@
+@import "tailwindcss";
+@import "@questpie/admin/client/styles/index.css";
+
+@source "../../../node_modules/@questpie/admin/";

package/templates/next/src/app/admin/layout.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+
+import { authClient } from "@/lib/auth-client";
+import { client } from "@/lib/client";
+import { queryClient } from "@/lib/query-client";
+import { admin } from "@/questpie/admin/admin";
+import { AdminLayoutProvider } from "@questpie/admin/client";
+
+import "./admin.css";
+
+function AdminLink({
+	to,
+	className,
+	children,
+	activeProps,
+	activeOptions,
+}: {
+	to: string;
+	className?: string;
+	children: React.ReactNode;
+	activeProps?: { className?: string };
+	activeOptions?: { exact?: boolean };
+}) {
+	const pathname = usePathname();
+	const isActive = activeOptions?.exact
+		? pathname === to
+		: pathname === to || pathname.startsWith(`${to}/`);
+	const mergedClassName = [className, isActive ? activeProps?.className : null]
+		.filter(Boolean)
+		.join(" ");
+
+	return (
+		<Link href={to} className={mergedClassName || undefined}>
+			{children}
+		</Link>
+	);
+}
+
+export default function AdminLayout({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	const pathname = usePathname();
+
+	return (
+		<AdminLayoutProvider
+			admin={admin}
+			client={client}
+			queryClient={queryClient}
+			authClient={authClient}
+			LinkComponent={AdminLink}
+			activeRoute={pathname}
+			basePath="/admin"
+			useServerTranslations
+		>
+			{children}
+		</AdminLayoutProvider>
+	);
+}

package/templates/next/src/app/api/[...all]/route.ts

@@ -0,0 +1,24 @@
+import { createFetchHandler } from "questpie/http";
+
+import { app } from "@/questpie/server/app";
+
+const handler = createFetchHandler(app, {
+	basePath: "/api",
+});
+
+const handleCmsRequest = async (request: Request) => {
+	const response = await handler(request);
+	return (
+		response ??
+		new Response(JSON.stringify({ error: "Not found" }), {
+			status: 404,
+			headers: { "Content-Type": "application/json" },
+		})
+	);
+};
+
+export const GET = handleCmsRequest;
+export const POST = handleCmsRequest;
+export const PUT = handleCmsRequest;
+export const DELETE = handleCmsRequest;
+export const PATCH = handleCmsRequest;

package/templates/next/src/app/layout.tsx

@@ -0,0 +1,24 @@
+import type { Metadata } from "next";
+
+import { Providers } from "./providers";
+
+import "@/styles.css";
+
+export const metadata: Metadata = {
+	title: "{{projectName}}",
+	description: "A QUESTPIE powered app",
+};
+
+export default function RootLayout({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	return (
+		<html lang="en">
+			<body className="bg-background text-foreground min-h-screen antialiased">
+				<Providers>{children}</Providers>
+			</body>
+		</html>
+	);
+}

package/templates/next/src/app/not-found.tsx

@@ -0,0 +1,18 @@
+import Link from "next/link";
+
+export default function NotFound() {
+	return (
+		<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
+				href="/"
+				className="text-primary mt-6 inline-block text-sm font-medium hover:underline"
+			>
+				Back to homepage
+			</Link>
+		</main>
+	);
+}