create-kuckit-app 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-kuckit-app",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Create a new Kuckit application",
 	"type": "module",
 	"license": "MIT",

package/templates/base/AGENTS.md

@@ -71,6 +71,209 @@ adapters → Implements ports, depends on domain
 api → Wires everything together
 ```
 
+## SDK Module System
+
+> **SDK Documentation**: For comprehensive module patterns, see [@kuckit/sdk](https://github.com/draphonix/kuckit)
+
+### Module Lifecycle
+
+Modules are loaded in a specific sequence:
+
+```
+1. createKuckitContainer()
+   └─► Core services registered (logger, db, cache, eventBus)
+
+2. loadKuckitModules({ modules: [...] })
+   ├─► Phase 1: register() - DI bindings for all modules
+   ├─► Phase 2: registerApi() - API registrations collected
+   ├─► Phase 3: onApiRegistrations callback (wire routers HERE)
+   ├─► Phase 4: onBootstrap() - Startup logic
+   └─► Phase 5: onComplete callback
+
+3. Application runs...
+
+4. disposeContainer()
+   └─► For each module: onShutdown()
+```
+
+### Core Services (CoreCradle)
+
+After container creation, these services are available via DI:
+
+| Token              | Type               | Lifetime  | Description                 |
+| ------------------ | ------------------ | --------- | --------------------------- |
+| `config`           | `CoreConfig`       | Singleton | Application configuration   |
+| `db`               | Drizzle            | Singleton | Database query builder      |
+| `dbPool`           | `Pool`             | Singleton | PostgreSQL connection pool  |
+| `logger`           | `Logger`           | Singleton | Structured logging          |
+| `eventBus`         | `EventBus`         | Singleton | Pub/sub event system        |
+| `clock`            | `Clock`            | Singleton | Time abstraction (testable) |
+| `cacheStore`       | `CacheStore`       | Singleton | Key-value cache             |
+| `rateLimiterStore` | `RateLimiterStore` | Singleton | Rate limiting               |
+| `auth`             | Better-Auth        | Singleton | Authentication utilities    |
+| `requestId`        | `string`           | Scoped    | Per-request unique ID       |
+| `requestLogger`    | `Logger`           | Scoped    | Logger with request context |
+
+### Server Module Definition
+
+```typescript
+import { defineKuckitModule, asClass, asFunction } from '@kuckit/sdk'
+
+export const kuckitModule = defineKuckitModule({
+	id: 'myapp.billing',
+	displayName: 'Billing',
+	version: '1.0.0',
+	capabilities: ['nav.item', 'api.public'],
+
+	register(ctx) {
+		// Phase 1: Register DI bindings
+		ctx.container.register({
+			invoiceRepository: asClass(InvoiceRepository).scoped(),
+			createInvoice: asFunction(makeCreateInvoiceUseCase).scoped(),
+		})
+	},
+
+	registerApi(ctx) {
+		// Phase 2: Register API routes
+		ctx.addApiRegistration({
+			type: 'rpc-router',
+			name: 'invoices',
+			router: invoicesRouter,
+		})
+	},
+
+	onBootstrap(ctx) {
+		// Phase 4: Startup logic (cache warming, logging, etc.)
+		ctx.container.resolve('logger').info('Billing module started')
+	},
+
+	onShutdown(ctx) {
+		// Cleanup on shutdown
+		ctx.container.resolve('logger').info('Billing module stopped')
+	},
+})
+```
+
+### Client Module Definition
+
+```typescript
+import { defineKuckitClientModule } from '@kuckit/sdk-react'
+
+export const kuckitClientModule = defineKuckitClientModule({
+	id: 'myapp.billing',
+	displayName: 'Billing',
+	capabilities: ['nav.item', 'dashboard.widget'],
+
+	routes: [
+		{
+			id: 'billing-invoices',
+			path: '/billing/invoices',
+			component: InvoicesPage,
+		},
+	],
+
+	navItems: [
+		{
+			id: 'billing-nav',
+			label: 'Billing',
+			href: '/billing/invoices',
+			icon: CreditCard,
+			order: 50,
+		},
+	],
+
+	slots: {
+		'dashboard.widgets': {
+			component: BillingWidget,
+			order: 10,
+		},
+	},
+})
+```
+
+### Module Capabilities
+
+Modules can declare capabilities for discovery:
+
+- `nav.item` - Provides navigation items
+- `settings.page` - Has settings page
+- `dashboard.widget` - Provides dashboard widgets
+- `api.webhook` - Exposes webhooks
+- `api.public` - Has public API endpoints
+- `slot.provider` - Provides slot components
+
+### useRpc with TanStack Query
+
+Module components use the `useRpc` hook to access the API:
+
+```typescript
+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 }) => Promise<Item>
+	}
+}
+
+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'] }),
+	})
+
+	// ... component render
+}
+```
+
+### oRPC Router Wiring (Important)
+
+oRPC's `RPCHandler` captures the router object at construction time. Module routers must be wired **before** the handler is created:
+
+1. Modules register routers via `registerApi()` hook
+2. Server wires routers in `onApiRegistrations` into a **mutable router object**
+3. `RPCHandler` is created **after** modules are loaded
+
+```typescript
+// apps/server/src/rpc-router-registry.ts
+export const rootRpcRouter = { ...appRouter }
+
+export const wireModuleRpcRouters = (registrations: ApiRegistration[]) => {
+	for (const reg of registrations) {
+		if (reg.type === 'rpc-router') {
+			rootRpcRouter[reg.name] = reg.router
+		}
+	}
+}
+```
+
+### Typing DI in Routers
+
+Use a module-local interface to type `context.di.cradle`:
+
+```typescript
+// In your module's router file
+interface BillingCradle {
+	createInvoice: (input: CreateInvoiceInput) => Promise<Invoice>
+}
+
+export const invoicesRouter = {
+	create: protectedProcedure.input(createInvoiceSchema).handler(async ({ input, context }) => {
+		const { createInvoice } = context.di.cradle as BillingCradle
+		return createInvoice(input)
+	}),
+}
+```
+
 ## Common Tasks
 
 ### Add a new API endpoint

package/templates/base/apps/server/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - Server App
 
-> See root [AGENTS.md](../../AGENTS.md) for project overview
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
 
 ## Purpose
 
@@ -8,13 +8,69 @@ Express backend hosting oRPC API, Better-Auth authentication, and the Kuckit mod
 
 ## Key Files
 
-| File                | Purpose                   |
-| ------------------- | ------------------------- |
-| `server.ts`         | Entry point, bootstrap    |
-| `container.ts`      | DI container setup        |
-| `config/modules.ts` | Module registration       |
-| `rpc.ts`            | oRPC handler setup        |
-| `auth.ts`           | Better-Auth configuration |
+| File                     | Purpose                    |
+| ------------------------ | -------------------------- |
+| `server.ts`              | Entry point, bootstrap     |
+| `container.ts`           | DI container setup         |
+| `config/modules.ts`      | Module registration        |
+| `rpc.ts`                 | oRPC handler setup         |
+| `rpc-router-registry.ts` | Mutable router for modules |
+| `auth.ts`                | Better-Auth configuration  |
+
+## Module Loading Sequence
+
+The server bootstraps in this order:
+
+```
+1. createKuckitContainer() - Core services (db, logger, cache, etc.)
+2. loadKuckitModules() with onApiRegistrations callback:
+   ├─► register() hooks run (DI bindings)
+   ├─► registerApi() hooks run (routers collected)
+   ├─► onApiRegistrations() - Wire routers to rootRpcRouter
+   └─► onBootstrap() hooks run (startup logic)
+3. setupRPC() - Create RPCHandler AFTER modules loaded
+4. Express listens
+```
+
+## Router Registry Pattern
+
+oRPC's `RPCHandler` captures the router at construction time. Modules wire their routers into a **mutable object** before the handler is created:
+
+```typescript
+// rpc-router-registry.ts
+export const rootRpcRouter = { ...appRouter }
+
+export const wireModuleRpcRouters = (registrations: ApiRegistration[]) => {
+	for (const reg of registrations) {
+		if (reg.type === 'rpc-router') {
+			rootRpcRouter[reg.name] = reg.router
+		}
+	}
+}
+```
+
+```typescript
+// server.ts
+await loadKuckitModules({
+	container,
+	modules: getModuleSpecs(),
+	onApiRegistrations: (registrations) => {
+		wireModuleRpcRouters(registrations) // Wire BEFORE setupRPC()
+	},
+})
+
+setupRPC(app) // Now create handler with fully-wired router
+```
+
+## Per-Request Scoping
+
+Each HTTP request gets a scoped container with:
+
+- `requestId` - Unique request identifier
+- `requestLogger` - Logger with request context
+- `session` - Current user session (if authenticated)
+
+Access scoped services in routers via `context.di.cradle`.
 
 ## Adding New Modules
 

package/templates/base/apps/web/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - Web App
 
-> See root [AGENTS.md](../../AGENTS.md) for project overview
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
 
 ## Purpose
 
@@ -8,13 +8,15 @@ React frontend using TanStack Router, TanStack Query, and Kuckit client modules.
 
 ## Key Files
 
-| File                             | Purpose                           |
-| -------------------------------- | --------------------------------- |
-| `main.tsx`                       | App entry point                   |
-| `modules.client.ts`              | Client module registration        |
-| `providers/KuckitProvider.tsx`   | Kuckit context setup              |
-| `providers/ServicesProvider.tsx` | Services context (RPC, auth)      |
-| `routes/`                        | TanStack Router file-based routes |
+| File                               | Purpose                           |
+| ---------------------------------- | --------------------------------- |
+| `main.tsx`                         | App entry point                   |
+| `modules.client.ts`                | Client module registration        |
+| `providers/KuckitProvider.tsx`     | Kuckit context setup              |
+| `providers/ServicesProvider.tsx`   | Services context (RPC, auth)      |
+| `routes/`                          | TanStack Router file-based routes |
+| `routes/$.tsx`                     | Catch-all for module routes       |
+| `components/KuckitModuleRoute.tsx` | Renders module-registered routes  |
 
 ## Adding Routes
 
@@ -24,6 +26,78 @@ Create files in `src/routes/`:
 - `src/routes/users/$id.tsx` → `/users/:id`
 - `src/routes/settings/index.tsx` → `/settings`
 
+**File-based routes take precedence** over module-registered routes.
+
+## Module Route Integration
+
+Modules register routes via `defineKuckitClientModule`. These are rendered via a catch-all pattern:
+
+1. Module registers route in `routes` array
+2. `RouteRegistry` collects routes during `loadKuckitClientModules()`
+3. Catch-all route (`$.tsx`) matches any unhandled path
+4. `KuckitModuleRoute` looks up path in registry and renders the component
+
+```tsx
+// routes/$.tsx - Catches module routes
+import { KuckitModuleRoute } from '@/components/KuckitModuleRoute'
+
+export function Route() {
+	return <KuckitModuleRoute />
+}
+```
+
+## Context Providers
+
+The app wraps content in Kuckit providers:
+
+```tsx
+<ServicesProvider>
+	{' '}
+	{/* RPC client, auth */}
+	<KuckitProvider>
+		{' '}
+		{/* Nav, slots, routes registries */}
+		<KuckitRpcProvider>
+			{' '}
+			{/* RPC context for modules */}
+			{children}
+		</KuckitRpcProvider>
+	</KuckitProvider>
+</ServicesProvider>
+```
+
+**Available hooks:**
+
+- `useRpc<T>()` - Get typed RPC client for API calls
+- `useNavItems()` - Flat navigation items list
+- `useNavTree()` - Hierarchical navigation tree
+- `useSlot(name)` - Get components for a slot
+- `useHasSlot(name)` - Check if slot has content
+
+## useRpc Hook
+
+Module components must use `useRpc()` to access the API:
+
+```tsx
+import { useRpc } from '@kuckit/sdk-react'
+import { useQuery } from '@tanstack/react-query'
+
+interface MyRpc {
+	items: { list: (input: {}) => Promise<Item[]> }
+}
+
+function MyComponent() {
+	const rpc = useRpc<MyRpc>()
+
+	const { data } = useQuery({
+		queryKey: ['items'],
+		queryFn: () => rpc.items.list({}),
+	})
+}
+```
+
+**Important**: Never use `import.meta.env.VITE_SERVER_URL` directly in module components - it's unavailable in external packages. The `useRpc` hook provides the correctly-configured client.
+
 ## Using Module UI Components
 
 ```tsx

package/templates/base/apps/web/src/components/KuckitModuleRoute.tsx

@@ -0,0 +1,82 @@
+import { useRouterState, Link, useNavigate } from '@tanstack/react-router'
+import { useKuckit } from '@/providers/KuckitProvider'
+import { useServices } from '@/providers/ServicesProvider'
+import { useEffect, useState } from 'react'
+
+/**
+ * Dynamic route renderer for Kuckit module routes.
+ *
+ * This component looks up the current path in the RouteRegistry
+ * and renders the corresponding module component if found.
+ *
+ * For routes with meta.requiresAuth: true, redirects to /login if not authenticated.
+ */
+export function KuckitModuleRoute() {
+	const { routeRegistry } = useKuckit()
+	const { authClient } = useServices()
+	const { location } = useRouterState()
+	const navigate = useNavigate()
+	const pathname = location.pathname
+
+	const [authChecked, setAuthChecked] = useState(false)
+	const [isAuthenticated, setIsAuthenticated] = useState(false)
+
+	// Find matching route in registry
+	const routeDef = routeRegistry.getAll().find((r) => r.path === pathname)
+
+	// Check auth for routes with requiresAuth
+	useEffect(() => {
+		async function checkAuth() {
+			if (!routeDef) {
+				setAuthChecked(true)
+				return
+			}
+
+			// Check if auth is required
+			if (routeDef.meta?.requiresAuth) {
+				const session = await authClient.getSession()
+				if (!session.data) {
+					// Redirect to login with return URL
+					navigate({
+						to: '/login',
+						search: { redirect: pathname },
+					})
+					return
+				}
+				setIsAuthenticated(true)
+			}
+			setAuthChecked(true)
+		}
+
+		checkAuth()
+	}, [routeDef, pathname, navigate, authClient])
+
+	// Show loading while checking auth for protected routes
+	if (routeDef?.meta?.requiresAuth && !authChecked) {
+		return (
+			<div className="flex items-center justify-center min-h-screen">
+				<div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
+			</div>
+		)
+	}
+
+	// Protected route - waiting for redirect
+	if (routeDef?.meta?.requiresAuth && !isAuthenticated) {
+		return null
+	}
+
+	if (!routeDef) {
+		return (
+			<div className="flex flex-col items-center justify-center min-h-[50vh] gap-4">
+				<h1 className="text-2xl font-bold">Page Not Found</h1>
+				<p className="text-muted-foreground">The page "{pathname}" could not be found.</p>
+				<Link to="/" className="text-primary hover:underline">
+					Go Home
+				</Link>
+			</div>
+		)
+	}
+
+	const Component = routeDef.component as React.ComponentType
+	return <Component />
+}

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/client'
 
 /**
  * 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/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/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