create-kuckit-app 0.2.0 → 0.3.0

package/templates/base/apps/web/src/components/ui/tooltip.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react'
+import * as TooltipPrimitive from '@radix-ui/react-tooltip'
+
+import { cn } from '@/lib/utils'
+
+function TooltipProvider({
+	delayDuration = 0,
+	...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+	return (
+		<TooltipPrimitive.Provider
+			data-slot="tooltip-provider"
+			delayDuration={delayDuration}
+			{...props}
+		/>
+	)
+}
+
+function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+	return (
+		<TooltipProvider>
+			<TooltipPrimitive.Root data-slot="tooltip" {...props} />
+		</TooltipProvider>
+	)
+}
+
+function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+	return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+	className,
+	sideOffset = 0,
+	children,
+	...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+	return (
+		<TooltipPrimitive.Portal>
+			<TooltipPrimitive.Content
+				data-slot="tooltip-content"
+				sideOffset={sideOffset}
+				className={cn(
+					'bg-foreground text-background animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance',
+					className
+				)}
+				{...props}
+			>
+				{children}
+				<TooltipPrimitive.Arrow className="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
+			</TooltipPrimitive.Content>
+		</TooltipPrimitive.Portal>
+	)
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }

package/templates/base/apps/web/src/hooks/use-mobile.ts

@@ -0,0 +1,19 @@
+import * as React from 'react'
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+	const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+	React.useEffect(() => {
+		const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+		const onChange = () => {
+			setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+		}
+		mql.addEventListener('change', onChange)
+		setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+		return () => mql.removeEventListener('change', onChange)
+	}, [])
+
+	return !!isMobile
+}

package/templates/base/apps/web/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs))
+}

package/templates/base/apps/web/src/modules.client.ts

@@ -1,4 +1,5 @@
 import type { ClientModuleSpec } from '@kuckit/sdk-react'
+import { kuckitClientModule as itemsClientModule } from '@__APP_NAME_KEBAB__/items-module/src/client-module'
 
 /**
  * Client modules configuration
@@ -7,9 +8,9 @@ import type { ClientModuleSpec } from '@kuckit/sdk-react'
  */
 export const getClientModuleSpecs = (): ClientModuleSpec[] => {
 	const modules: ClientModuleSpec[] = [
-		// KUCKIT_MODULES_START
-		// Client modules will be added here
-		// KUCKIT_MODULES_END
+		// KUCKIT_CLIENT_MODULES_START
+		{ module: itemsClientModule },
+		// KUCKIT_CLIENT_MODULES_END
 	]
 
 	return modules

package/templates/base/apps/web/src/providers/KuckitProvider.tsx

@@ -1,10 +1,5 @@
 import { createContext, useContext, useEffect, useState, useMemo, type ReactNode } from 'react'
-import {
-	RouterProvider,
-	createRouter,
-	createRoute,
-	type RouteComponent,
-} from '@tanstack/react-router'
+import { RouterProvider, createRouter } from '@tanstack/react-router'
 import {
 	loadKuckitClientModules,
 	KuckitNavProvider,
@@ -16,7 +11,6 @@ import {
 	type SlotRegistry,
 } from '@kuckit/sdk-react'
 import { routeTree } from '../routeTree.gen'
-import { Route as rootRoute } from '../routes/__root'
 import { useServices } from './ServicesProvider'
 import { getClientModuleSpecs } from '../modules.client'
 
@@ -81,26 +75,8 @@ export function KuckitProvider({ children }: KuckitProviderProps) {
 		}
 	}, [orpc, queryClient])
 
-	// Build router with module routes
 	const router = useMemo(() => {
 		if (!loadResult) return null
-
-		const moduleRouteDefs = loadResult.routeRegistry.getAll()
-		const moduleRoutes = moduleRouteDefs.map((routeDef) =>
-			createRoute({
-				getParentRoute: () => rootRoute,
-				path: routeDef.path,
-				component: routeDef.component as RouteComponent,
-			})
-		)
-
-		if (moduleRoutes.length > 0) {
-			console.log(
-				`Loaded ${moduleRoutes.length} module routes:`,
-				moduleRouteDefs.map((r) => r.path)
-			)
-		}
-
 		return createRouter({
 			routeTree,
 			defaultPreload: 'intent',

package/templates/base/apps/web/src/routes/$.tsx

@@ -0,0 +1,14 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { KuckitModuleRoute } from '@/components/KuckitModuleRoute'
+
+/**
+ * Catch-all route for KuckitModule routes at root level.
+ *
+ * This route matches any path not handled by other file-based routes
+ * and uses the KuckitModuleRoute component to look up and render
+ * the appropriate module component from the RouteRegistry.
+ */
+// @ts-expect-error - Route types are generated when dev server runs
+export const Route = createFileRoute('/$')({
+	component: KuckitModuleRoute,
+})

package/templates/base/apps/web/src/routes/dashboard/$.tsx

@@ -0,0 +1,9 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { KuckitModuleRoute } from '@/components/KuckitModuleRoute'
+
+/**
+ * Catch-all route for KuckitModule routes under /dashboard.
+ */
+export const Route = createFileRoute('/dashboard/$')({
+	component: KuckitModuleRoute,
+})

package/templates/base/apps/web/src/routes/dashboard/index.tsx

@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { DashboardOverview } from '@/components/dashboard/dashboard-overview'
+
+export const Route = createFileRoute('/dashboard/')({
+	component: DashboardOverview,
+})

package/templates/base/apps/web/src/routes/dashboard.tsx

@@ -0,0 +1,25 @@
+import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
+import { DashboardLayout } from '@/components/dashboard/dashboard-layout'
+import { createAuthClientService } from '../services/auth-client'
+
+export const Route = createFileRoute('/dashboard')({
+	beforeLoad: async () => {
+		const authClient = createAuthClientService()
+		const session = await authClient.getSession()
+		if (!session.data) {
+			throw redirect({
+				to: '/login',
+			})
+		}
+		return { session }
+	},
+	component: DashboardLayoutRoute,
+})
+
+function DashboardLayoutRoute() {
+	return (
+		<DashboardLayout>
+			<Outlet />
+		</DashboardLayout>
+	)
+}

package/templates/base/apps/web/tsconfig.json

@@ -3,7 +3,11 @@
 	"compilerOptions": {
 		"lib": ["DOM", "DOM.Iterable", "ESNext"],
 		"jsx": "react-jsx",
-		"noEmit": true
+		"noEmit": true,
+		"baseUrl": ".",
+		"paths": {
+			"@/*": ["./src/*"]
+		}
 	},
 	"include": ["src"]
 }

package/templates/base/apps/web/vite.config.ts

@@ -1,7 +1,13 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+import path from 'path'
 
 export default defineConfig({
 	plugins: [TanStackRouterVite(), react()],
+	resolve: {
+		alias: {
+			'@': path.resolve(__dirname, './src'),
+		},
+	},
 })

package/templates/base/packages/api/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - API Package
 
-> See root [AGENTS.md](../../AGENTS.md) for project overview
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
 
 ## Purpose
 
@@ -13,15 +13,54 @@ Shared API context, types, and procedure definitions for oRPC.
 | `context.ts` | Request context type definitions |
 | `index.ts`   | Public exports                   |
 
-## Usage
+## Procedure Types
 
 ```typescript
-import { type Context, protectedProcedure } from '@__APP_NAME_KEBAB__/api'
+import { publicProcedure, protectedProcedure } from '@__APP_NAME_KEBAB__/api'
+
+// Public - no authentication required
+export const healthRouter = {
+	ping: publicProcedure.handler(() => 'pong'),
+}
+
+// Protected - requires authenticated user
+export const itemsRouter = {
+	list: protectedProcedure.handler(async ({ context }) => {
+		const userId = context.session?.user?.id
+		// ...
+	}),
+}
 ```
 
 ## Context Structure
 
 The API context provides:
 
-- `container` - Scoped DI container for the request
-- `user` - Authenticated user (when using `protectedProcedure`)
+- `di` - Scoped DI container for the request
+- `session` - Current user session (when using `protectedProcedure`)
+
+## Typing DI Access in Routers
+
+Use a module-local interface to type `context.di.cradle`:
+
+```typescript
+// In your module's router file
+interface ItemsCradle {
+	itemRepository: ItemRepository
+	createItem: (input: CreateItemInput) => Promise<Item>
+}
+
+export const itemsRouter = {
+	create: protectedProcedure.input(createItemSchema).handler(async ({ input, context }) => {
+		const { createItem } = context.di.cradle as ItemsCradle
+		return createItem(input)
+	}),
+}
+```
+
+**Why module-local interfaces:**
+
+- Type assertion stays within the module
+- Module remains self-contained
+- Server app doesn't need to know about module internals
+- Scales to any number of modules without server changes

package/templates/base/packages/auth/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - Auth Package
 
-> See root [AGENTS.md](../../AGENTS.md) for project overview
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
 
 ## Purpose
 
@@ -36,6 +36,22 @@ await authClient.signOut()
 const session = await authClient.getSession()
 ```
 
+## Session in oRPC Context
+
+The current user session is available in `protectedProcedure` handlers:
+
+```typescript
+import { protectedProcedure } from '@__APP_NAME_KEBAB__/api'
+
+export const myRouter = {
+	getProfile: protectedProcedure.handler(async ({ context }) => {
+		const userId = context.session?.user?.id
+		const userEmail = context.session?.user?.email
+		// ... use session data
+	}),
+}
+```
+
 ## Configuration
 
 Auth requires these environment variables:

package/templates/base/packages/db/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - Database Package
 
-> See root [AGENTS.md](../../AGENTS.md) for project overview
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
 
 ## Purpose
 
@@ -50,6 +50,21 @@ bun run db:studio
    bun run db:migrate
    ```
 
+## Module Schema Pattern
+
+Modules can define their own schemas in `adapters/`:
+
+```typescript
+// packages/items-module/src/adapters/items.schema.ts
+export const itemsTable = pgTable('items', {
+	id: uuid('id').primaryKey().defaultRandom(),
+	userId: text('user_id').notNull(),
+	name: text('name').notNull(),
+})
+```
+
+The schema is imported by `drizzle.config.ts` for migration generation.
+
 ## Connection
 
 ```typescript

package/templates/base/packages/items-module/AGENTS.md

@@ -1,6 +1,9 @@
 # AGENTS.md - Items Module
 
-> See root [AGENTS.md](../../AGENTS.md) for project overview
+> **SDK Documentation**: For detailed module patterns, see the root [AGENTS.md](../../AGENTS.md) SDK Module System section
+>
+> - Server modules: `defineKuckitModule()` from `@kuckit/sdk`
+> - Client modules: `defineKuckitClientModule()` from `@kuckit/sdk-react`
 
 ## Purpose
 
@@ -110,3 +113,98 @@ export const kuckitModule = defineKuckitModule({
 6. Implement use cases
 7. Create API router
 8. Register in server's `config/modules.ts`
+
+## Registration in Apps
+
+### Server Registration
+
+```typescript
+// apps/server/src/config/modules.ts
+import { kuckitModule as itemsModule } from '@__APP_NAME_KEBAB__/items-module'
+
+export const modules = [itemsModule]
+```
+
+### Client Registration
+
+```typescript
+// apps/web/src/modules.client.ts
+import { kuckitClientModule as itemsClient } from '@__APP_NAME_KEBAB__/items-module/client'
+
+export const clientModules = [{ module: itemsClient }]
+```
+
+## Client Module Pattern
+
+The client module registers routes, navigation items, and slots:
+
+```typescript
+// client-module.ts
+import { defineKuckitClientModule } from '@kuckit/sdk-react'
+import { ItemsPage } from './ui/ItemsPage'
+
+export const kuckitClientModule = defineKuckitClientModule({
+	id: 'items',
+	displayName: 'Items',
+
+	routes: [
+		{
+			id: 'items-page',
+			path: '/items',
+			component: ItemsPage,
+			meta: { requiresAuth: true },
+		},
+	],
+
+	navItems: [
+		{
+			id: 'items-nav',
+			label: 'Items',
+			href: '/items',
+			order: 20,
+		},
+	],
+})
+```
+
+## Using useRpc in Components
+
+Module components access the API via the `useRpc` hook:
+
+```typescript
+// ui/ItemsPage.tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { useRpc } from '@kuckit/sdk-react'
+
+interface ItemsRpc {
+	items: {
+		list: (input: Record<string, never>) => Promise<Item[]>
+		create: (input: { name: string; description?: string }) => Promise<Item>
+		delete: (input: { id: string }) => Promise<void>
+	}
+}
+
+export function ItemsPage() {
+	const rpc = useRpc<ItemsRpc>()
+	const queryClient = useQueryClient()
+
+	const { data: items = [], isLoading } = useQuery({
+		queryKey: ['items'],
+		queryFn: () => rpc.items.list({}),
+	})
+
+	const createMutation = useMutation({
+		mutationFn: (data: { name: string }) => rpc.items.create(data),
+		onSuccess: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
+	})
+
+	const deleteMutation = useMutation({
+		mutationFn: (id: string) => rpc.items.delete({ id }),
+		onSuccess: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
+	})
+
+	// ... render items list with create/delete handlers
+}
+```
+
+**Important**: Never use `import.meta.env` directly in module components - use `useRpc()` instead. Module packages are bundled separately and don't have access to the host app's environment variables.

package/templates/base/packages/items-module/src/ui/ItemsPage.tsx

@@ -1,4 +1,6 @@
-import { useState, useEffect } from 'react'
+import { useState } from 'react'
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { useRpc } from '@kuckit/sdk-react'
 
 interface Item {
 	id: string
@@ -8,85 +10,63 @@ interface Item {
 	updatedAt: Date
 }
 
+interface ItemsRpc {
+	items: {
+		list: (input: Record<string, never>) => Promise<Item[]>
+		create: (input: { name: string; description?: string }) => Promise<Item>
+		delete: (input: { id: string }) => Promise<void>
+	}
+}
+
 /**
  * Items page component
- * Demonstrates CRUD operations using the items module
+ * Demonstrates CRUD operations using the items module with useRpc and TanStack Query
  */
 export function ItemsPage() {
-	const [items, setItems] = useState<Item[]>([])
+	const rpc = useRpc<ItemsRpc>()
+	const queryClient = useQueryClient()
 	const [newItemName, setNewItemName] = useState('')
 	const [newItemDescription, setNewItemDescription] = useState('')
-	const [loading, setLoading] = useState(true)
-	const [error, setError] = useState<string | null>(null)
 
-	const apiUrl = import.meta.env.VITE_API_URL || 'http://localhost:3000'
+	const {
+		data: items = [],
+		isLoading,
+		error,
+	} = useQuery({
+		queryKey: ['items'],
+		queryFn: () => rpc.items.list({}),
+	})
 
-	// Fetch items on mount
-	useEffect(() => {
-		fetchItems()
-	}, [])
+	const createMutation = useMutation({
+		mutationFn: (data: { name: string; description?: string }) => rpc.items.create(data),
+		onSuccess: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
+	})
 
-	const fetchItems = async () => {
-		try {
-			setLoading(true)
-			const response = await fetch(`${apiUrl}/rpc/items.list`, {
-				method: 'POST',
-				headers: { 'Content-Type': 'application/json' },
-				credentials: 'include',
-				body: JSON.stringify({}),
-			})
-			if (response.ok) {
-				const data = await response.json()
-				setItems(data)
-			}
-		} catch {
-			setError('Failed to load items')
-		} finally {
-			setLoading(false)
-		}
-	}
+	const deleteMutation = useMutation({
+		mutationFn: (id: string) => rpc.items.delete({ id }),
+		onSuccess: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
+	})
 
 	const createItem = async (e: React.FormEvent) => {
 		e.preventDefault()
 		if (!newItemName.trim()) return
 
-		try {
-			const response = await fetch(`${apiUrl}/rpc/items.create`, {
-				method: 'POST',
-				headers: { 'Content-Type': 'application/json' },
-				credentials: 'include',
-				body: JSON.stringify({
-					name: newItemName,
-					description: newItemDescription || undefined,
-				}),
-			})
-			if (response.ok) {
-				setNewItemName('')
-				setNewItemDescription('')
-				fetchItems()
+		createMutation.mutate(
+			{ name: newItemName, description: newItemDescription || undefined },
+			{
+				onSuccess: () => {
+					setNewItemName('')
+					setNewItemDescription('')
+				},
 			}
-		} catch {
-			setError('Failed to create item')
-		}
+		)
 	}
 
-	const deleteItem = async (id: string) => {
-		try {
-			const response = await fetch(`${apiUrl}/rpc/items.delete`, {
-				method: 'POST',
-				headers: { 'Content-Type': 'application/json' },
-				credentials: 'include',
-				body: JSON.stringify({ id }),
-			})
-			if (response.ok) {
-				fetchItems()
-			}
-		} catch {
-			setError('Failed to delete item')
-		}
+	const deleteItem = (id: string) => {
+		deleteMutation.mutate(id)
 	}
 
-	if (loading) {
+	if (isLoading) {
 		return <div style={{ padding: '2rem' }}>Loading items...</div>
 	}
 
@@ -94,12 +74,9 @@ export function ItemsPage() {
 		<div style={{ padding: '2rem', fontFamily: 'system-ui', maxWidth: '600px', margin: '0 auto' }}>
 			<h1>Items</h1>
 
-			{error && (
+			{(error || createMutation.error || deleteMutation.error) && (
 				<div style={{ color: 'red', marginBottom: '1rem' }}>
-					{error}
-					<button onClick={() => setError(null)} style={{ marginLeft: '1rem' }}>
-						Dismiss
-					</button>
+					{error?.message || createMutation.error?.message || deleteMutation.error?.message}
 				</div>
 			)}
 
@@ -120,8 +97,12 @@ export function ItemsPage() {
 						onChange={(e) => setNewItemDescription(e.target.value)}
 						style={{ padding: '0.5rem', fontSize: '1rem' }}
 					/>
-					<button type="submit" style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}>
-						Add Item
+					<button
+						type="submit"
+						disabled={createMutation.isPending}
+						style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+					>
+						{createMutation.isPending ? 'Adding...' : 'Add Item'}
 					</button>
 				</div>
 			</form>
@@ -148,6 +129,7 @@ export function ItemsPage() {
 						</div>
 						<button
 							onClick={() => deleteItem(item.id)}
+							disabled={deleteMutation.isPending}
 							style={{ cursor: 'pointer', color: 'red', background: 'none', border: 'none' }}
 						>
 							Delete

package/templates/base/apps/web/src/lib/kuckit-router.ts

@@ -1,42 +0,0 @@
-import { createRoute, type AnyRoute, type RouteComponent } from '@tanstack/react-router'
-import type { QueryClient } from '@tanstack/react-query'
-import type { RouteRegistry, RouteDefinition } from '@kuckit/sdk-react'
-import type { ORPCUtils } from '../services/types'
-
-export interface KuckitRouterContext {
-	orpc: ORPCUtils
-	queryClient: QueryClient
-}
-
-/**
- * Build TanStack Router routes from a RouteRegistry
- */
-export function buildModuleRoutes(routeRegistry: RouteRegistry, rootRoute: AnyRoute): AnyRoute[] {
-	const routes = routeRegistry.getAll()
-	const routeMap = new Map<string, AnyRoute>()
-
-	for (const routeDef of routes) {
-		const route = createModuleRoute(routeDef, rootRoute)
-		routeMap.set(routeDef.id, route)
-	}
-
-	const topLevelRoutes = routes
-		.filter((r) => !r.parentRouteId || r.parentRouteId === '__root__')
-		.map((r) => routeMap.get(r.id)!)
-		.filter(Boolean)
-
-	return topLevelRoutes
-}
-
-function createModuleRoute(routeDef: RouteDefinition, parentRoute: AnyRoute): AnyRoute {
-	return createRoute({
-		getParentRoute: () => parentRoute,
-		path: routeDef.path,
-		component: routeDef.component as RouteComponent,
-		...(routeDef.meta?.title && {
-			head: () => ({
-				meta: [{ title: routeDef.meta!.title }],
-			}),
-		}),
-	})
-}