create-kuckit-app 0.1.0 → 0.2.0

package/templates/base/apps/server/src/health.ts

@@ -0,0 +1,27 @@
+import type { Express } from 'express'
+import type { AppContainer } from './container'
+
+export const setupHealth = (app: Express, container: AppContainer) => {
+	app.get('/health', async (_req, res) => {
+		const { dbPool } = container.cradle
+
+		try {
+			const client = await dbPool.connect()
+			await client.query('SELECT 1')
+			client.release()
+
+			res.status(200).json({
+				status: 'healthy',
+				timestamp: new Date().toISOString(),
+				checks: { database: 'ok' },
+			})
+		} catch (error) {
+			console.error('[Health] Database check failed:', error)
+			res.status(503).json({
+				status: 'unhealthy',
+				timestamp: new Date().toISOString(),
+				checks: { database: 'failed' },
+			})
+		}
+	})
+}

package/templates/base/apps/server/src/middleware/container.ts

@@ -0,0 +1,41 @@
+import type { Express, Request, Response, NextFunction } from 'express'
+import { asValue } from 'awilix'
+import { buildRootContainer, type AppContainer } from '../container'
+
+let rootContainer: AppContainer
+
+/**
+ * Initialize and setup container middleware
+ * Must be awaited before using the container
+ */
+export const setupContainerMiddleware = async (app: Express): Promise<void> => {
+	rootContainer = await buildRootContainer()
+
+	app.use((req: Request, res: Response, next: NextFunction) => {
+		req.scope = rootContainer.createScope()
+
+		req.scope.register({
+			requestId: asValue(crypto.randomUUID()),
+		})
+
+		res.on('finish', () => {
+			req.scope?.dispose()
+		})
+
+		res.on('close', () => {
+			req.scope?.dispose()
+		})
+
+		next()
+	})
+}
+
+/**
+ * Get root container (for graceful shutdown)
+ */
+export const getRootContainer = (): AppContainer => {
+	if (!rootContainer) {
+		throw new Error('Container not initialized')
+	}
+	return rootContainer
+}

package/templates/base/apps/server/src/rpc-router-registry.ts

@@ -0,0 +1,26 @@
+import type { ApiRegistration } from '@kuckit/sdk'
+
+/**
+ * Central mutable RPC router object used by RPCHandler.
+ *
+ * Module routers are wired into this object during the SDK loader's
+ * "wire" phase, before RPCHandler is instantiated.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const rootRpcRouter: Record<string, any> = {}
+
+/**
+ * Wire module RPC routers into the central router object.
+ * Called from the SDK loader's onApiRegistrations callback.
+ */
+export const wireModuleRpcRouters = (registrations: ApiRegistration[]): void => {
+	for (const reg of registrations) {
+		if (reg.type !== 'rpc-router') continue
+
+		if (rootRpcRouter[reg.name]) {
+			throw new Error(`Duplicate RPC router name: "${reg.name}"`)
+		}
+
+		rootRpcRouter[reg.name] = reg.router
+	}
+}

package/templates/base/apps/server/src/rpc.ts

@@ -0,0 +1,31 @@
+import { RPCHandler } from '@orpc/server/node'
+import { onError } from '@orpc/server'
+import { createContext } from '@__APP_NAME_KEBAB__/api'
+import type { Express } from 'express'
+import { rootRpcRouter } from './rpc-router-registry'
+
+/**
+ * Setup oRPC handler
+ *
+ * IMPORTANT: This must be called AFTER setupContainerMiddleware() has completed,
+ * which ensures all module routers have been wired into rootRpcRouter.
+ */
+export const setupRPC = (app: Express) => {
+	const rpcHandler = new RPCHandler(rootRpcRouter, {
+		interceptors: [
+			onError((error) => {
+				console.error('[RPC Error]', error)
+			}),
+		],
+	})
+
+	app.use(async (req, res, next) => {
+		const result = await rpcHandler.handle(req, res, {
+			prefix: '/rpc',
+			context: await createContext({ req }),
+		})
+
+		if (result.matched) return
+		next()
+	})
+}

package/templates/base/apps/server/src/server.ts

@@ -1,39 +1,49 @@
 import 'dotenv/config'
-import express from 'express'
-import cors from 'cors'
-import { createKuckitContainer, loadKuckitModules } from '@kuckit/sdk'
-import { getModuleSpecs } from './config/modules.js'
+import { createApp } from './app'
+import { setupContainerMiddleware, getRootContainer } from './middleware/container'
+import { setupAuth } from './auth'
+import { setupRPC } from './rpc'
+import { setupHealth } from './health'
+import { disposeContainer } from './container'
 
-const app = express()
-const port = process.env.PORT ?? 3000
+/**
+ * Bootstrap and start server
+ */
+const bootstrap = async () => {
+	const app = createApp()
 
-app.use(cors())
-app.use(express.json())
+	await setupContainerMiddleware(app)
+	const rootContainer = getRootContainer()
 
-async function bootstrap() {
-	// Create DI container
-	const container = createKuckitContainer({
-		env: process.env.NODE_ENV ?? 'development',
-	})
+	setupAuth(app)
+	setupRPC(app)
+	setupHealth(app, rootContainer)
 
-	// Load modules
-	await loadKuckitModules({
-		container,
-		env: process.env.NODE_ENV ?? 'development',
-		modules: getModuleSpecs(),
-		onComplete: () => {
-			console.log('All modules loaded')
-		},
+	const port = process.env.PORT || 3000
+	const server = app.listen(port, () => {
+		console.log(`Server is running on port ${port}`)
 	})
 
-	// Health check
-	app.get('/health', (_req, res) => {
-		res.json({ status: 'ok' })
-	})
+	const shutdown = async () => {
+		console.log('Shutting down gracefully...')
 
-	app.listen(port, () => {
-		console.log(`Server running at http://localhost:${port}`)
-	})
+		server.close(async () => {
+			await disposeContainer(rootContainer)
+			console.log('Server closed')
+			process.exit(0)
+		})
+
+		setTimeout(() => {
+			console.error('Forced shutdown')
+			process.exit(1)
+		}, 10000)
+	}
+
+	process.on('SIGTERM', shutdown)
+	process.on('SIGINT', shutdown)
 }
 
-bootstrap().catch(console.error)
+bootstrap().catch((error) => {
+	console.error('Failed to start server:', error)
+	process.exit(1)
+})

package/templates/base/apps/web/.env.example

@@ -0,0 +1,4 @@
+# Web Environment Variables
+
+# API URL for the backend server
+VITE_API_URL=http://localhost:3000

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

@@ -0,0 +1,53 @@
+# AGENTS.md - Web App
+
+> See root [AGENTS.md](../../AGENTS.md) for project overview
+
+## Purpose
+
+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 |
+
+## Adding Routes
+
+Create files in `src/routes/`:
+
+- `src/routes/about.tsx` → `/about`
+- `src/routes/users/$id.tsx` → `/users/:id`
+- `src/routes/settings/index.tsx` → `/settings`
+
+## Using Module UI Components
+
+```tsx
+import { ItemsPage } from '@__APP_NAME_KEBAB__/items-module/ui'
+
+// In your route component
+export function Route() {
+	return <ItemsPage />
+}
+```
+
+## Adding Client Modules
+
+1. Import in `modules.client.ts`:
+
+   ```typescript
+   import { kuckitClientModule as myClientModule } from '@__APP_NAME_KEBAB__/my-module/client'
+
+   export const clientModules = [
+   	itemsClientModule,
+   	myClientModule, // Add here
+   ]
+   ```
+
+## Environment Variables
+
+See `.env.example` in this directory.

package/templates/base/apps/web/index.html

@@ -6,7 +6,7 @@
 		<title>__APP_NAME__</title>
 	</head>
 	<body>
-		<div id="root"></div>
+		<div id="app"></div>
 		<script type="module" src="/src/main.tsx"></script>
 	</body>
 </html>

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

@@ -1,5 +1,7 @@
 {
-	"name": "__APP_NAME_KEBAB__-web",
+	"name": "@__APP_NAME_KEBAB__/web",
+	"version": "0.0.1",
+	"private": true,
 	"type": "module",
 	"scripts": {
 		"dev": "vite --port=3001",
@@ -7,12 +9,22 @@
 		"check-types": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@kuckit/sdk-react": "^0.1.0",
+		"@kuckit/sdk-react": "^1.0.0",
+		"@orpc/client": "^1.10.0",
+		"@orpc/tanstack-query": "^1.10.0",
 		"@tanstack/react-query": "^5.85.5",
+		"@tanstack/react-router": "^1.114.25",
+		"better-auth": "^1.3.28",
 		"react": "^19.1.0",
-		"react-dom": "^19.1.0"
+		"react-dom": "^19.1.0",
+		"zod": "^4.1.11",
+		"@__APP_NAME_KEBAB__/auth": "workspace:*"
 	},
 	"devDependencies": {
+		"@tanstack/react-router-devtools": "^1.114.27",
+		"@tanstack/router-plugin": "^1.114.27",
+		"@tanstack/react-query-devtools": "^5.85.5",
+		"@types/node": "^22.13.13",
 		"@types/react": "~19.1.10",
 		"@types/react-dom": "^19.0.4",
 		"@vitejs/plugin-react": "^4.3.4",

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

@@ -0,0 +1,42 @@
+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 }],
+			}),
+		}),
+	})
+}

package/templates/base/apps/web/src/main.tsx

@@ -1,14 +1,26 @@
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { App } from './App.js'
-
-const queryClient = new QueryClient()
-
-createRoot(document.getElementById('root')!).render(
-	<StrictMode>
-		<QueryClientProvider client={queryClient}>
-			<App />
-		</QueryClientProvider>
-	</StrictMode>
-)
+import { createRouter } from '@tanstack/react-router'
+import ReactDOM from 'react-dom/client'
+import { routeTree } from './routeTree.gen'
+import { ServicesProvider } from './providers/ServicesProvider'
+import { KuckitProvider } from './providers/KuckitProvider'
+
+declare module '@tanstack/react-router' {
+	interface Register {
+		router: ReturnType<typeof createRouter<typeof routeTree>>
+	}
+}
+
+const rootElement = document.getElementById('app')
+
+if (!rootElement) {
+	throw new Error('Root element not found')
+}
+
+if (!rootElement.innerHTML) {
+	const root = ReactDOM.createRoot(rootElement)
+	root.render(
+		<ServicesProvider>
+			<KuckitProvider />
+		</ServicesProvider>
+	)
+}

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

@@ -0,0 +1,147 @@
+import { createContext, useContext, useEffect, useState, useMemo, type ReactNode } from 'react'
+import {
+	RouterProvider,
+	createRouter,
+	createRoute,
+	type RouteComponent,
+} from '@tanstack/react-router'
+import {
+	loadKuckitClientModules,
+	KuckitNavProvider,
+	KuckitSlotProvider,
+	KuckitRpcProvider,
+	type LoadClientModulesResult,
+	type RouteRegistry,
+	type NavRegistry,
+	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'
+
+interface KuckitContextValue {
+	routeRegistry: RouteRegistry
+	navRegistry: NavRegistry
+	slotRegistry: SlotRegistry
+	isLoaded: boolean
+}
+
+const KuckitContext = createContext<KuckitContextValue | null>(null)
+
+/**
+ * Hook to access Kuckit registries
+ */
+export function useKuckit(): KuckitContextValue {
+	const ctx = useContext(KuckitContext)
+	if (!ctx) {
+		throw new Error('useKuckit must be used within a KuckitProvider')
+	}
+	return ctx
+}
+
+interface KuckitProviderProps {
+	children?: ReactNode
+}
+
+/**
+ * KuckitProvider handles module loading and router creation
+ */
+export function KuckitProvider({ children }: KuckitProviderProps) {
+	const { orpc, queryClient, rpcClient } = useServices()
+	const [loadResult, setLoadResult] = useState<LoadClientModulesResult | null>(null)
+	const [error, setError] = useState<Error | null>(null)
+
+	useEffect(() => {
+		let cancelled = false
+
+		const loadModules = async () => {
+			try {
+				const result = await loadKuckitClientModules({
+					orpc,
+					queryClient,
+					env: import.meta.env.MODE,
+					modules: getClientModuleSpecs(),
+				})
+
+				if (!cancelled) {
+					setLoadResult(result)
+				}
+			} catch (err) {
+				if (!cancelled) {
+					setError(err instanceof Error ? err : new Error(String(err)))
+				}
+			}
+		}
+
+		loadModules()
+
+		return () => {
+			cancelled = true
+		}
+	}, [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',
+			context: { orpc, queryClient },
+		})
+	}, [loadResult, orpc, queryClient])
+
+	if (error) {
+		return (
+			<div style={{ padding: '2rem', color: 'red' }}>
+				<h2>Failed to load modules</h2>
+				<p>{error.message}</p>
+			</div>
+		)
+	}
+
+	if (!loadResult || !router) {
+		return (
+			<div style={{ padding: '2rem' }}>
+				<p>Loading...</p>
+			</div>
+		)
+	}
+
+	const contextValue: KuckitContextValue = {
+		routeRegistry: loadResult.routeRegistry,
+		navRegistry: loadResult.navRegistry,
+		slotRegistry: loadResult.slotRegistry,
+		isLoaded: true,
+	}
+
+	return (
+		<KuckitContext.Provider value={contextValue}>
+			<KuckitRpcProvider client={rpcClient}>
+				<KuckitNavProvider registry={loadResult.navRegistry}>
+					<KuckitSlotProvider registry={loadResult.slotRegistry}>
+						<RouterProvider router={router} />
+						{children}
+					</KuckitSlotProvider>
+				</KuckitNavProvider>
+			</KuckitRpcProvider>
+		</KuckitContext.Provider>
+	)
+}

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

@@ -0,0 +1,47 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import { QueryClientProvider } from '@tanstack/react-query'
+import {
+	createQueryClient,
+	createRPCLink,
+	createRPCClient,
+	createORPCUtils,
+	createAuthClientService,
+	type Services,
+} from '../services'
+
+const ServicesContext = createContext<Services | null>(null)
+
+interface ServicesProviderProps {
+	children: ReactNode
+}
+
+export function ServicesProvider({ children }: ServicesProviderProps) {
+	const services = useMemo<Services>(() => {
+		const queryClient = createQueryClient()
+		const link = createRPCLink()
+		const rpcClient = createRPCClient(link)
+		const orpc = createORPCUtils(rpcClient)
+		const authClient = createAuthClientService()
+
+		return {
+			queryClient,
+			rpcClient,
+			orpc,
+			authClient,
+		}
+	}, [])
+
+	return (
+		<ServicesContext.Provider value={services}>
+			<QueryClientProvider client={services.queryClient}>{children}</QueryClientProvider>
+		</ServicesContext.Provider>
+	)
+}
+
+export function useServices(): Services {
+	const context = useContext(ServicesContext)
+	if (!context) {
+		throw new Error('useServices must be used within a ServicesProvider')
+	}
+	return context
+}

package/templates/base/apps/web/src/routeTree.gen.ts

@@ -0,0 +1,91 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+// Import Routes
+
+import { Route as rootRoute } from './routes/__root'
+import { Route as LoginImport } from './routes/login'
+import { Route as IndexImport } from './routes/index'
+
+// Create/Update Routes
+
+const LoginRoute = LoginImport.update({
+  id: '/login',
+  path: '/login',
+  getParentRoute: () => rootRoute,
+} as any)
+
+const IndexRoute = IndexImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRoute,
+} as any)
+
+// Populate the FileRoutesByPath interface
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexImport
+      parentRoute: typeof rootRoute
+    }
+    '/login': {
+      id: '/login'
+      path: '/login'
+      fullPath: '/login'
+      preLoaderRoute: typeof LoginImport
+      parentRoute: typeof rootRoute
+    }
+  }
+}
+
+// Create and export the route tree
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/login': typeof LoginRoute
+}
+
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/login': typeof LoginRoute
+}
+
+export interface FileRoutesById {
+  __root__: typeof rootRoute
+  '/': typeof IndexRoute
+  '/login': typeof LoginRoute
+}
+
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/login'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/login'
+  id: '__root__' | '/' | '/login'
+  fileRoutesById: FileRoutesById
+}
+
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  LoginRoute: typeof LoginRoute
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  LoginRoute: LoginRoute,
+}
+
+export const routeTree = rootRoute
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()