create-velox-app 0.6.61 → 0.6.62

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # create-velox-app
 
+## 0.6.62
+
+### Patch Changes
+
+- add Common Gotchas section to all template CLAUDE.md files + add dynamic database display name to CLAUDE.md templates
+
 ## 0.6.61
 
 ### Patch Changes

package/dist/templates/placeholders.d.ts

@@ -32,6 +32,8 @@ export declare const PLACEHOLDERS: {
     readonly DATABASE_PROVIDER: "__DATABASE_PROVIDER__";
     /** Database URL for .env files */
     readonly DATABASE_URL: "__DATABASE_URL__";
+    /** Display-friendly database name (SQLite, PostgreSQL) */
+    readonly DATABASE_DISPLAY: "__DATABASE_DISPLAY__";
 };
 /**
  * Default template configuration for templates that don't need real values.

package/dist/templates/placeholders.js

@@ -35,6 +35,8 @@ export const PLACEHOLDERS = {
     DATABASE_PROVIDER: '__DATABASE_PROVIDER__',
     /** Database URL for .env files */
     DATABASE_URL: '__DATABASE_URL__',
+    /** Display-friendly database name (SQLite, PostgreSQL) */
+    DATABASE_DISPLAY: '__DATABASE_DISPLAY__',
 };
 /**
  * Default template configuration for templates that don't need real values.
@@ -141,6 +143,17 @@ function getDatabaseUrl(database) {
     }
     return 'file:./dev.db';
 }
+/**
+ * Get the display-friendly database name.
+ */
+function getDatabaseDisplay(database) {
+    const displayNames = {
+        sqlite: 'SQLite',
+        postgresql: 'PostgreSQL',
+        mysql: 'MySQL',
+    };
+    return displayNames[database];
+}
 /**
  * Apply placeholder replacements to template content.
  *
@@ -164,6 +177,7 @@ export function applyPlaceholders(content, config) {
         [PLACEHOLDERS.WEB_PORT]: '8080',
         [PLACEHOLDERS.DATABASE_PROVIDER]: config.database,
         [PLACEHOLDERS.DATABASE_URL]: getDatabaseUrl(config.database),
+        [PLACEHOLDERS.DATABASE_DISPLAY]: getDatabaseDisplay(config.database),
     };
     let result = content;
     for (const [placeholder, value] of Object.entries(replacements)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-velox-app",
-  "version": "0.6.61",
+  "version": "0.6.62",
   "description": "Project scaffolder for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",

package/src/templates/source/root/CLAUDE.auth.md

@@ -7,7 +7,7 @@ This file provides guidance to Claude Code and other AI assistants.
 **__PROJECT_NAME__** is a VeloxTS full-stack application with:
 - **Backend**: Fastify + VeloxTS (apps/api)
 - **Frontend**: React + Vite + TanStack Router (apps/web)
-- **Database**: Prisma with SQLite
+- **Database**: Prisma with __DATABASE_DISPLAY__
 - **Auth**: JWT authentication with guards
 
 ## Commands
@@ -142,6 +142,110 @@ JWT_REFRESH_SECRET=<64+ chars>   # Generate: openssl rand -base64 64
 | `patchUser` | PATCH | `/users/:id` |
 | `deleteUser` | DELETE | `/users/:id` |
 
+## Common Gotchas (IMPORTANT)
+
+These patterns prevent common mistakes when building VeloxTS applications.
+
+### Procedure Builder Syntax
+
+**Always call `procedure()` with parentheses:**
+
+```typescript
+// ✅ Correct
+getCampaign: procedure()
+  .guard(authenticated)
+  .input(schema)
+  .query(...)
+
+// ❌ Wrong - causes "procedure.guard is not a function"
+getCampaign: procedure
+  .guard(authenticated)
+```
+
+### Custom REST Routes
+
+When using `.rest()` to override routes, do NOT include the API prefix:
+
+```typescript
+// ✅ Correct - prefix is applied automatically
+.rest({ method: 'POST', path: '/campaigns/:id/activate' })
+
+// ❌ Wrong - results in /api/api/campaigns/:id/activate
+.rest({ method: 'POST', path: '/api/campaigns/:id/activate' })
+```
+
+**Note:** Path parameters (`:id`) are NOT auto-extracted into input. Pass them in the request body.
+
+### Handling Prisma Decimals in Zod Schemas
+
+Prisma returns `Decimal` objects for decimal fields. Standard Zod validation fails.
+
+**Input schemas** - use `z.coerce.number()`:
+```typescript
+bidAmount: z.coerce.number().positive().max(1000)
+```
+
+**Output schemas** - use `z.any().transform()`:
+```typescript
+bidAmount: z.any().transform((val) => Number(val))
+balance: z.any().transform((val) => Number(val))
+```
+
+**Dates** - use `z.coerce.date()`:
+```typescript
+createdAt: z.coerce.date()
+updatedAt: z.coerce.date()
+```
+
+### Extending User Context
+
+The `ctx.user` object is populated by `userLoader` in `src/config/auth.ts`.
+
+To add fields to `ctx.user` (e.g., `organizationId`):
+
+1. Update `userLoader`:
+```typescript
+async function userLoader(userId: string) {
+  const user = await db.user.findUnique({ where: { id: userId } });
+  return {
+    id: user.id,
+    email: user.email,
+    roles: parseUserRoles(user.roles),
+    organizationId: user.organizationId, // Add new fields here
+  };
+}
+```
+
+2. Update related schemas (`UserSchema`, `UpdateUserInput`, etc.).
+
+### Role Configuration
+
+Roles are stored as a JSON string array in the database (e.g., `["ADMIN"]`).
+
+When changing roles, update ALL locations:
+- `prisma/schema.prisma` - Role enum
+- `src/config/auth.ts` - `ALLOWED_ROLES` and `parseUserRoles`
+- `src/utils/auth.ts` - `ALLOWED_ROLES` (if duplicated)
+- `src/schemas/auth.ts` - Role validation schemas
+
+### MCP Project Path
+
+For Claude Desktop, specify the project path explicitly in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "velox": {
+      "command": "npx",
+      "args": ["@veloxts/mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+CLI fallback: `__RUN_CMD__ velox make procedure Posts --crud`
+
 ## Guards and Policies
 
 ### Using Guards

package/src/templates/source/root/CLAUDE.default.md

@@ -7,7 +7,7 @@ This file provides guidance to Claude Code and other AI assistants.
 **__PROJECT_NAME__** is a VeloxTS full-stack application with:
 - **Backend**: Fastify + VeloxTS (apps/api)
 - **Frontend**: React + Vite + TanStack Router (apps/web)
-- **Database**: Prisma with SQLite
+- **Database**: Prisma with __DATABASE_DISPLAY__
 
 ## Commands
 
@@ -122,6 +122,77 @@ VeloxTS provides end-to-end type safety without code generation:
 | `patchUser` | PATCH | `/users/:id` |
 | `deleteUser` | DELETE | `/users/:id` |
 
+## Common Gotchas (IMPORTANT)
+
+These patterns prevent common mistakes when building VeloxTS applications.
+
+### Procedure Builder Syntax
+
+**Always call `procedure()` with parentheses:**
+
+```typescript
+// ✅ Correct
+getPost: procedure()
+  .input(schema)
+  .query(...)
+
+// ❌ Wrong - causes "procedure.input is not a function"
+getPost: procedure
+  .input(schema)
+```
+
+### Custom REST Routes
+
+When using `.rest()` to override routes, do NOT include the API prefix:
+
+```typescript
+// ✅ Correct - prefix is applied automatically
+.rest({ method: 'POST', path: '/posts/:id/publish' })
+
+// ❌ Wrong - results in /api/api/posts/:id/publish
+.rest({ method: 'POST', path: '/api/posts/:id/publish' })
+```
+
+**Note:** Path parameters (`:id`) are NOT auto-extracted into input. Pass them in the request body.
+
+### Handling Prisma Decimals in Zod Schemas
+
+Prisma returns `Decimal` objects for decimal fields. Standard Zod validation fails.
+
+**Input schemas** - use `z.coerce.number()`:
+```typescript
+price: z.coerce.number().positive()
+```
+
+**Output schemas** - use `z.any().transform()`:
+```typescript
+price: z.any().transform((val) => Number(val))
+```
+
+**Dates** - use `z.coerce.date()`:
+```typescript
+createdAt: z.coerce.date()
+updatedAt: z.coerce.date()
+```
+
+### MCP Project Path
+
+For Claude Desktop, specify the project path explicitly in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "velox": {
+      "command": "npx",
+      "args": ["@veloxts/mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+CLI fallback: `__RUN_CMD__ velox make procedure Posts --crud`
+
 ## Database
 
 After schema changes:

package/src/templates/source/root/CLAUDE.trpc.md

@@ -7,7 +7,7 @@ This file provides guidance to Claude Code and other AI assistants.
 **__PROJECT_NAME__** is a VeloxTS full-stack application using **tRPC-only** architecture:
 - **Backend**: Fastify + VeloxTS + tRPC (apps/api)
 - **Frontend**: React + Vite + TanStack Router (apps/web)
-- **Database**: Prisma with SQLite
+- **Database**: Prisma with __DATABASE_DISPLAY__
 
 This template uses tRPC exclusively for type-safe internal communication. No REST adapter is included.
 
@@ -181,6 +181,63 @@ This auto-generates REST endpoints from procedure names:
 - `posts.byId` → `GET /api/posts/:id`
 - `posts.create` → `POST /api/posts`
 
+## Common Gotchas (IMPORTANT)
+
+These patterns prevent common mistakes when building VeloxTS applications.
+
+### Procedure Builder Syntax
+
+**Always call `procedure()` with parentheses:**
+
+```typescript
+// ✅ Correct
+list: procedure()
+  .output(schema)
+  .query(...)
+
+// ❌ Wrong - causes "procedure.output is not a function"
+list: procedure
+  .output(schema)
+```
+
+### Handling Prisma Decimals in Zod Schemas
+
+Prisma returns `Decimal` objects for decimal fields. Standard Zod validation fails.
+
+**Input schemas** - use `z.coerce.number()`:
+```typescript
+price: z.coerce.number().positive()
+```
+
+**Output schemas** - use `z.any().transform()`:
+```typescript
+price: z.any().transform((val) => Number(val))
+```
+
+**Dates** - use `z.coerce.date()`:
+```typescript
+createdAt: z.coerce.date()
+updatedAt: z.coerce.date()
+```
+
+### MCP Project Path
+
+For Claude Desktop, specify the project path explicitly in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "velox": {
+      "command": "npx",
+      "args": ["@veloxts/mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+CLI fallback: `__RUN_CMD__ velox make procedure Posts`
+
 ## Database
 
 After schema changes:

package/src/templates/source/root/package.json

@@ -10,6 +10,7 @@
     "dev": "__DEV_CMD__",
     "build": "__WS_ALL__ build",
     "type-check": "__WS_ALL__ type-check",
+    "velox": "velox",
     "db:push": "__WS_API__ db:push",
     "db:generate": "__WS_API__ db:generate",
     "db:studio": "__WS_API__ db:studio"

package/src/templates/source/rsc/CLAUDE.md

@@ -157,6 +157,75 @@ __RUN_CMD__ start       # Start production server
 - `PUT /api/users/:id` - Update user
 - `DELETE /api/users/:id` - Delete user
 
+## Common Gotchas (IMPORTANT)
+
+These patterns prevent common mistakes when building VeloxTS applications.
+
+### Procedure Builder Syntax
+
+**Always call `procedure()` with parentheses:**
+
+```typescript
+// ✅ Correct
+getPost: procedure()
+  .input(schema)
+  .query(...)
+
+// ❌ Wrong - causes "procedure.input is not a function"
+getPost: procedure
+  .input(schema)
+```
+
+### Custom REST Routes
+
+When using `.rest()` to override routes, do NOT include the API prefix:
+
+```typescript
+// ✅ Correct - prefix is applied automatically
+.rest({ method: 'POST', path: '/posts/:id/publish' })
+
+// ❌ Wrong - results in /api/api/posts/:id/publish
+.rest({ method: 'POST', path: '/api/posts/:id/publish' })
+```
+
+### Handling Prisma Decimals in Zod Schemas
+
+Prisma returns `Decimal` objects for decimal fields. Standard Zod validation fails.
+
+**Input schemas** - use `z.coerce.number()`:
+```typescript
+price: z.coerce.number().positive()
+```
+
+**Output schemas** - use `z.any().transform()`:
+```typescript
+price: z.any().transform((val) => Number(val))
+```
+
+**Dates** - use `z.coerce.date()`:
+```typescript
+createdAt: z.coerce.date()
+updatedAt: z.coerce.date()
+```
+
+### MCP Project Path
+
+For Claude Desktop, specify the project path explicitly in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "velox": {
+      "command": "npx",
+      "args": ["@veloxts/mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+CLI fallback: `__RUN_CMD__ velox make procedure Posts --crud`
+
 ## AI-Powered Development with MCP
 
 VeloxTS includes a **Model Context Protocol (MCP) server** that gives AI assistants like Claude direct access to your project structure. This enables intelligent code assistance with full awareness of your procedures, schemas, routes, and error codes.

package/src/templates/source/rsc/package.json

@@ -7,6 +7,7 @@
     "dev": "vinxi dev --port __API_PORT__",
     "build": "vinxi build",
     "start": "vinxi start --port __API_PORT__",
+    "velox": "velox",
     "db:generate": "prisma generate",
     "db:push": "prisma db push",
     "db:migrate": "prisma migrate dev",
@@ -35,6 +36,7 @@
     "@types/node": "25.0.3",
     "@types/react": "19.2.7",
     "@types/react-dom": "19.2.3",
+    "@veloxts/cli": "__VELOXTS_VERSION__",
     "prisma": "7.2.0",
     "typescript": "5.9.3"
   }

package/src/templates/source/rsc-auth/CLAUDE.md

@@ -229,6 +229,106 @@ JWT_REFRESH_SECRET="..."
 - `PUT /api/users/:id` - Update user
 - `DELETE /api/users/:id` - Delete user
 
+## Common Gotchas (IMPORTANT)
+
+These patterns prevent common mistakes when building VeloxTS applications.
+
+### Procedure Builder Syntax
+
+**Always call `procedure()` with parentheses:**
+
+```typescript
+// ✅ Correct
+getUser: procedure()
+  .guard(authenticated)
+  .input(schema)
+  .query(...)
+
+// ❌ Wrong - causes "procedure.guard is not a function"
+getUser: procedure
+  .guard(authenticated)
+```
+
+### Custom REST Routes
+
+When using `.rest()` to override routes, do NOT include the API prefix:
+
+```typescript
+// ✅ Correct - prefix is applied automatically
+.rest({ method: 'POST', path: '/users/:id/activate' })
+
+// ❌ Wrong - results in /api/api/users/:id/activate
+.rest({ method: 'POST', path: '/api/users/:id/activate' })
+```
+
+### Handling Prisma Decimals in Zod Schemas
+
+Prisma returns `Decimal` objects for decimal fields. Standard Zod validation fails.
+
+**Input schemas** - use `z.coerce.number()`:
+```typescript
+price: z.coerce.number().positive()
+```
+
+**Output schemas** - use `z.any().transform()`:
+```typescript
+price: z.any().transform((val) => Number(val))
+```
+
+**Dates** - use `z.coerce.date()`:
+```typescript
+createdAt: z.coerce.date()
+updatedAt: z.coerce.date()
+```
+
+### Extending User Context
+
+The `ctx.user` object is populated by `userLoader` in `src/api/utils/auth.ts`.
+
+To add fields to `ctx.user` (e.g., `organizationId`):
+
+1. Update `userLoader`:
+```typescript
+async function userLoader(userId: string) {
+  const user = await db.user.findUnique({ where: { id: userId } });
+  return {
+    id: user.id,
+    email: user.email,
+    roles: parseUserRoles(user.roles),
+    organizationId: user.organizationId, // Add new fields here
+  };
+}
+```
+
+2. Update related schemas (`UserSchema`, `UpdateUserInput`, etc.).
+
+### Role Configuration
+
+Roles are stored as a JSON string array in the database (e.g., `["ADMIN"]`).
+
+When changing roles, update ALL locations:
+- `prisma/schema.prisma` - Role enum
+- `src/api/utils/auth.ts` - `ALLOWED_ROLES` and `parseUserRoles`
+- `src/api/schemas/auth.ts` - Role validation schemas
+
+### MCP Project Path
+
+For Claude Desktop, specify the project path explicitly in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "velox": {
+      "command": "npx",
+      "args": ["@veloxts/mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+CLI fallback: `__RUN_CMD__ velox make procedure Posts --crud`
+
 ## AI-Powered Development with MCP
 
 VeloxTS includes a **Model Context Protocol (MCP) server** that gives AI assistants like Claude direct access to your project structure. This enables intelligent code assistance with full awareness of your procedures, schemas, routes, and error codes.

package/src/templates/source/rsc-auth/package.json

@@ -7,6 +7,7 @@
     "dev": "vinxi dev --port __API_PORT__",
     "build": "vinxi build",
     "start": "vinxi start --port __API_PORT__",
+    "velox": "velox",
     "db:generate": "prisma generate",
     "db:push": "prisma db push",
     "db:migrate": "prisma migrate dev",
@@ -38,6 +39,7 @@
     "@types/node": "25.0.3",
     "@types/react": "19.2.7",
     "@types/react-dom": "19.2.3",
+    "@veloxts/cli": "__VELOXTS_VERSION__",
     "prisma": "7.2.0",
     "typescript": "5.9.3"
   }