create-velox-app 0.4.14 → 0.6.23

package/src/templates/source/rsc/app/pages/users/_layout.tsx

@@ -0,0 +1,104 @@
+/**
+ * Users Segment Layout
+ *
+ * A directory-based layout that wraps all pages under /users/*.
+ * Demonstrates segment layouts (also called per-directory layouts).
+ *
+ * Layout inheritance chain for /users/[id]/posts:
+ *   RootLayout -> UsersLayout -> Page
+ */
+
+import type { ReactNode } from 'react';
+
+interface UsersLayoutProps {
+  children: ReactNode;
+  params?: Record<string, string>;
+}
+
+export default function UsersLayout({ children }: UsersLayoutProps) {
+  return (
+    <div className="users-layout">
+      <style>{`
+        .users-layout {
+          min-height: 60vh;
+        }
+
+        .users-header {
+          background: linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%);
+          color: white;
+          padding: 1.5rem 2rem;
+          border-radius: 8px 8px 0 0;
+          margin: -2rem -2rem 2rem -2rem;
+        }
+
+        .users-header h2 {
+          font-size: 0.875rem;
+          text-transform: uppercase;
+          opacity: 0.8;
+          margin-bottom: 0.25rem;
+        }
+
+        .users-header nav {
+          display: flex;
+          gap: 1.5rem;
+          margin-top: 1rem;
+        }
+
+        .users-header a {
+          color: white;
+          text-decoration: none;
+          opacity: 0.8;
+          font-size: 0.875rem;
+          transition: opacity 0.2s;
+        }
+
+        .users-header a:hover {
+          opacity: 1;
+        }
+
+        .users-breadcrumb {
+          font-size: 0.875rem;
+          color: rgba(255,255,255,0.7);
+          margin-top: 0.5rem;
+        }
+
+        .users-breadcrumb a {
+          color: rgba(255,255,255,0.7);
+        }
+
+        .users-content {
+          background: white;
+          border-radius: 0 0 8px 8px;
+          padding: 2rem;
+          margin: -2rem -2rem 0 -2rem;
+          box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }
+
+        .segment-badge {
+          display: inline-block;
+          background: #e0e7ff;
+          color: #4338ca;
+          font-size: 0.625rem;
+          text-transform: uppercase;
+          padding: 0.25rem 0.5rem;
+          border-radius: 4px;
+          margin-bottom: 1rem;
+        }
+      `}</style>
+
+      <header className="users-header">
+        <h2>User Management</h2>
+        <nav>
+          <a href="/users">All Users</a>
+          <a href="/">Home</a>
+          <a href="/settings">Settings</a>
+        </nav>
+      </header>
+
+      <div className="users-content">
+        <span className="segment-badge">Users Section</span>
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/templates/source/rsc/app/pages/users.tsx

@@ -0,0 +1,44 @@
+/**
+ * Users Page
+ *
+ * A React Server Component that runs on the server at request time.
+ * Demonstrates direct database access from RSC.
+ */
+
+import { db } from '../../src/api/database.js';
+
+export default async function UsersPage() {
+  const users = await db.user.findMany({
+    orderBy: { createdAt: 'desc' },
+    take: 10,
+  });
+
+  return (
+    <div className="users-page">
+      <h1>Users</h1>
+
+      {users.length === 0 ? (
+        <p className="empty-state">
+          No users yet. Create one via the API at <code>POST /api/users</code>
+        </p>
+      ) : (
+        <ul className="user-list">
+          {users.map((user) => (
+            <li key={user.id} className="user-card">
+              <a href={`/users/${user.id}`} className="user-link">
+                <span className="user-name">{user.name}</span>
+                <span className="user-email">{user.email}</span>
+              </a>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <footer className="cta">
+        <p>
+          Edit <code>app/pages/users.tsx</code> to customize this page.
+        </p>
+      </footer>
+    </div>
+  );
+}

package/src/templates/source/rsc/app.config.ts

@@ -0,0 +1,12 @@
+/**
+ * Vinxi Application Configuration
+ *
+ * VeloxTS full-stack application with React Server Components.
+ * All options have sensible defaults - only specify what you need to change.
+ */
+
+import { defineVeloxApp } from '@veloxts/web';
+
+export default defineVeloxApp({
+  port: __API_PORT__,
+});

package/src/templates/source/rsc/env.example

@@ -0,0 +1,6 @@
+# Database
+DATABASE_URL="file:./dev.db"
+
+# Server
+PORT=__API_PORT__
+NODE_ENV=development

package/src/templates/source/rsc/gitignore

@@ -0,0 +1,34 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+.vinxi/
+.output/
+
+# Database
+*.db
+*.db-journal
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# TypeScript
+*.tsbuildinfo

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

@@ -0,0 +1,41 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vinxi dev --port __API_PORT__",
+    "build": "vinxi build",
+    "start": "vinxi start --port __API_PORT__",
+    "db:generate": "prisma generate",
+    "db:push": "prisma db push",
+    "db:migrate": "prisma migrate dev",
+    "db:studio": "prisma studio",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@prisma/adapter-better-sqlite3": "7.2.0",
+    "@prisma/client": "7.2.0",
+    "@prisma/client-runtime-utils": "7.2.0",
+    "better-sqlite3": "12.5.0",
+    "@veloxts/core": "__VELOXTS_VERSION__",
+    "@veloxts/orm": "__VELOXTS_VERSION__",
+    "@veloxts/router": "__VELOXTS_VERSION__",
+    "@veloxts/validation": "__VELOXTS_VERSION__",
+    "@veloxts/web": "__VELOXTS_VERSION__",
+    "@vinxi/server-functions": "0.5.1",
+    "dotenv": "17.2.3",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "vinxi": "0.5.10",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.3",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "prisma": "7.2.0",
+    "typescript": "5.9.3",
+    "vite": "7.3.0"
+  }
+}

package/src/templates/source/rsc/prisma/schema.prisma

@@ -0,0 +1,34 @@
+// Prisma Schema for VeloxTS Full-Stack Application
+
+generator client {
+  provider = "prisma-client-js"
+  output   = "../node_modules/.prisma/client"
+}
+
+datasource db {
+  provider = "sqlite"
+}
+
+model User {
+  id        String   @id @default(uuid())
+  name      String
+  email     String   @unique
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  posts     Post[]
+
+  @@map("users")
+}
+
+model Post {
+  id        String   @id @default(uuid())
+  title     String
+  content   String?
+  published Boolean  @default(false)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@map("posts")
+}

package/src/templates/source/rsc/prisma.config.ts

@@ -0,0 +1,22 @@
+/**
+ * Prisma Configuration (Prisma 7.x)
+ *
+ * Database URL is configured here instead of schema.prisma.
+ */
+
+import 'dotenv/config';
+
+import { defineConfig } from 'prisma/config';
+
+const databaseUrl = process.env.DATABASE_URL;
+
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL environment variable is required');
+}
+
+export default defineConfig({
+  schema: './prisma/schema.prisma',
+  datasource: {
+    url: databaseUrl,
+  },
+});

package/src/templates/source/rsc/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="6" fill="#6366f1"/>
+  <text x="50%" y="50%" dominant-baseline="central" text-anchor="middle" fill="white" font-family="system-ui" font-weight="bold" font-size="18">V</text>
+</svg>

package/src/templates/source/rsc/src/api/database.ts

@@ -0,0 +1,72 @@
+/**
+ * Database Configuration
+ *
+ * Prisma client instance for database access.
+ * Uses Laravel-style `db` export for consistency.
+ *
+ * Note: Prisma 7 requires using driver adapters for direct database connections.
+ * We explicitly load dotenv here because Vite's SSR module evaluation
+ * doesn't always have access to .env variables.
+ */
+
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Type imports (erased at runtime, safe for ESM)
+import type { PrismaBetterSqlite3 as PrismaBetterSqlite3Type } from '@prisma/adapter-better-sqlite3';
+import type { PrismaClient as PrismaClientType } from '@prisma/client';
+import dotenv from 'dotenv';
+
+// Runtime imports using createRequire for Node.js v24+ CJS interop
+const require = createRequire(import.meta.url);
+const { PrismaBetterSqlite3 } = require('@prisma/adapter-better-sqlite3') as {
+  PrismaBetterSqlite3: typeof PrismaBetterSqlite3Type;
+};
+const { PrismaClient } = require('@prisma/client') as {
+  PrismaClient: typeof PrismaClientType;
+};
+
+// Get the project root directory (2 levels up from src/api/)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..', '..');
+
+// Load .env file explicitly for Vite SSR compatibility
+// Use project root for reliable path resolution
+dotenv.config({ path: resolve(projectRoot, '.env') });
+
+declare global {
+  // Allow global `var` declarations for hot reload in development
+  // eslint-disable-next-line no-var
+  var __db: PrismaClient | undefined;
+}
+
+/**
+ * Create a Prisma client instance using the SQLite adapter.
+ *
+ * Prisma 7 Breaking Change:
+ * - `datasourceUrl` and `datasources` options removed from PrismaClient
+ * - Must use driver adapters for direct database connections
+ * - Validates that DATABASE_URL is set before creating the client
+ */
+function createPrismaClient(): PrismaClient {
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    throw new Error(
+      '[VeloxTS] DATABASE_URL environment variable is not set. ' +
+        'Ensure .env file exists in project root with DATABASE_URL defined.'
+    );
+  }
+
+  // Prisma 7 requires driver adapters for direct connections
+  const adapter = new PrismaBetterSqlite3({ url: databaseUrl });
+  return new PrismaClient({ adapter });
+}
+
+// Use global singleton for hot reload in development
+export const db = globalThis.__db ?? createPrismaClient();
+
+if (process.env.NODE_ENV !== 'production') {
+  globalThis.__db = db;
+}

package/src/templates/source/rsc/src/api/handler.ts

@@ -0,0 +1,53 @@
+/**
+ * API Handler
+ *
+ * This creates the Fastify API handler that gets embedded in Vinxi.
+ * All routes under /api/* are handled by this Fastify instance.
+ *
+ * IMPORTANT:
+ * - Vinxi HTTP routers expect h3 event handlers as default export
+ * - We use lazy initialization (factory function) to avoid Vite SSR module issues
+ * - createH3ApiHandler handles the Fastify app lifecycle and initialization
+ */
+
+import { veloxApp } from '@veloxts/core';
+import { databasePlugin } from '@veloxts/orm';
+import { rest } from '@veloxts/router';
+import { createH3ApiHandler } from '@veloxts/web';
+
+import { db } from './database.js';
+import { healthProcedures } from './procedures/health.js';
+import { postProcedures } from './procedures/posts.js';
+import { userProcedures } from './procedures/users.js';
+
+// Export router type for frontend type safety
+const router = { health: healthProcedures, users: userProcedures, posts: postProcedures };
+export type AppRouter = typeof router;
+
+/**
+ * Export the h3 event handler for Vinxi embedding.
+ *
+ * We use a factory function for lazy initialization to avoid
+ * Vite trying to evaluate the Fastify app during build time.
+ * The app is initialized on the first HTTP request.
+ */
+export default createH3ApiHandler({
+  app: async () => {
+    const app = await veloxApp();
+
+    // Register database plugin
+    await app.register(databasePlugin({ client: db }));
+
+    // Register REST routes from procedures
+    app.routes(
+      rest([healthProcedures, userProcedures, postProcedures], {
+        prefix: '', // No prefix - Vinxi handles /api/*
+      })
+    );
+
+    // Return the underlying Fastify instance for the h3 adapter
+    // The adapter will call ready() on it
+    return app.server;
+  },
+  basePath: '/api',
+});

package/src/templates/source/rsc/src/api/procedures/health.ts

@@ -0,0 +1,48 @@
+/**
+ * Health Check Procedures
+ *
+ * API endpoints for application health monitoring.
+ */
+
+import { defineProcedures, procedure } from '@veloxts/router';
+
+import { db } from '../database.js';
+
+export const healthProcedures = defineProcedures('health', {
+  /**
+   * Basic health check
+   * GET /api/health
+   */
+  getHealth: procedure()
+    .rest({ method: 'GET', path: '/health' })
+    .query(() => ({
+      status: 'healthy',
+      timestamp: new Date().toISOString(),
+      uptime: process.uptime(),
+    })),
+
+  /**
+   * Readiness check (includes database)
+   * GET /api/health/ready
+   */
+  getReady: procedure()
+    .rest({ method: 'GET', path: '/health/ready' })
+    .query(async () => {
+      try {
+        // Test database connection
+        await db.$queryRaw`SELECT 1`;
+
+        return {
+          status: 'ready',
+          database: 'connected',
+          timestamp: new Date().toISOString(),
+        };
+      } catch {
+        return {
+          status: 'not_ready',
+          database: 'disconnected',
+          timestamp: new Date().toISOString(),
+        };
+      }
+    }),
+});

package/src/templates/source/rsc/src/api/procedures/posts.ts

@@ -0,0 +1,151 @@
+/**
+ * Post Procedures
+ *
+ * Nested CRUD operations for posts under users.
+ * Uses .parent('users') to enable automatic path parameter merging.
+ * Routes: /api/users/:userId/posts/*
+ */
+
+import { defineProcedures, procedure } from '@veloxts/router';
+import { z } from 'zod';
+
+import { db } from '../database.js';
+import {
+  CreatePostSchema,
+  PostSchema,
+  PostWithUserSchema,
+  UpdatePostSchema,
+} from '../schemas/post.js';
+
+export const postProcedures = defineProcedures('posts', {
+  /**
+   * List all posts for a user
+   * GET /api/users/:userId/posts
+   */
+  listPosts: procedure()
+    .parent('users')
+    .input(z.object({ userId: z.string().uuid() }))
+    .output(z.array(PostSchema))
+    .query(async ({ input }) => {
+      // Verify user exists
+      const user = await db.user.findUnique({
+        where: { id: input.userId },
+      });
+
+      if (!user) {
+        throw Object.assign(new Error('User not found'), { statusCode: 404 });
+      }
+
+      return db.post.findMany({
+        where: { userId: input.userId },
+        orderBy: { createdAt: 'desc' },
+      });
+    }),
+
+  /**
+   * Get a single post by ID
+   * GET /api/users/:userId/posts/:id
+   */
+  getPost: procedure()
+    .parent('users')
+    .input(z.object({ userId: z.string().uuid(), id: z.string().uuid() }))
+    .output(PostWithUserSchema)
+    .query(async ({ input }) => {
+      const post = await db.post.findFirst({
+        where: {
+          id: input.id,
+          userId: input.userId,
+        },
+        include: {
+          user: {
+            select: { id: true, name: true },
+          },
+        },
+      });
+
+      if (!post) {
+        throw Object.assign(new Error('Post not found'), { statusCode: 404 });
+      }
+
+      return post;
+    }),
+
+  /**
+   * Create a new post for a user
+   * POST /api/users/:userId/posts
+   */
+  createPost: procedure()
+    .parent('users')
+    .input(CreatePostSchema.extend({ userId: z.string().uuid() }))
+    .output(PostSchema)
+    .mutation(async ({ input }) => {
+      const { userId, ...data } = input;
+
+      // Verify user exists
+      const user = await db.user.findUnique({
+        where: { id: userId },
+      });
+
+      if (!user) {
+        throw Object.assign(new Error('User not found'), { statusCode: 404 });
+      }
+
+      return db.post.create({
+        data: {
+          ...data,
+          userId,
+        },
+      });
+    }),
+
+  /**
+   * Update an existing post
+   * PUT /api/users/:userId/posts/:id
+   */
+  updatePost: procedure()
+    .parent('users')
+    .input(UpdatePostSchema.extend({ userId: z.string().uuid(), id: z.string().uuid() }))
+    .output(PostSchema)
+    .mutation(async ({ input }) => {
+      const { id, userId, ...data } = input;
+
+      // Verify post belongs to user
+      const post = await db.post.findFirst({
+        where: { id, userId },
+      });
+
+      if (!post) {
+        throw Object.assign(new Error('Post not found'), { statusCode: 404 });
+      }
+
+      return db.post.update({
+        where: { id },
+        data,
+      });
+    }),
+
+  /**
+   * Delete a post
+   * DELETE /api/users/:userId/posts/:id
+   */
+  deletePost: procedure()
+    .parent('users')
+    .input(z.object({ userId: z.string().uuid(), id: z.string().uuid() }))
+    .output(z.object({ success: z.boolean() }))
+    .mutation(async ({ input }) => {
+      // Verify post belongs to user
+      const post = await db.post.findFirst({
+        where: { id: input.id, userId: input.userId },
+      });
+
+      if (!post) {
+        throw Object.assign(new Error('Post not found'), { statusCode: 404 });
+      }
+
+      await db.post.delete({
+        where: { id: input.id },
+      });
+
+      return { success: true };
+    }),
+});