create-kuckit-app 0.3.3 → 0.3.5

package/package.json

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

package/templates/base/AGENTS.md

@@ -342,6 +342,51 @@ See `.env.example` for required variables:
 - `PORT` - Server port (default: 3000)
 - `VITE_API_URL` - API URL for frontend
 
+## Troubleshooting
+
+### 404 Errors on API Calls
+
+**Symptom**: `POST /rpc/items/list 404 (Not Found)` with multiple retries
+
+**Cause**: Server and client modules are out of sync. The client has a module registered but the server doesn't.
+
+**Fix**: Ensure both files register the same modules:
+
+- `apps/server/src/config/modules.ts` - Server modules
+- `apps/web/src/modules.client.ts` - Client modules
+
+**Prevention**: Run `bunx kuckit doctor` to detect mismatches.
+
+### "Relation does not exist" Database Errors
+
+**Symptom**: `error: relation "items" does not exist`
+
+**Cause**: Module schema not registered in `drizzle.config.ts`.
+
+**Fix**: Add the module's schema path to `packages/db/drizzle.config.ts`:
+
+```typescript
+schema: [
+	resolve(currentDirPath, './src/schema'),
+	resolve(currentDirPath, '../your-module/src/adapters/schema.drizzle.ts'),
+],
+```
+
+Then run:
+
+```bash
+bun run db:generate
+bun run db:migrate
+```
+
+### Module Not Appearing in Navigation
+
+**Symptom**: Module pages work but nav items don't show.
+
+**Cause**: Client module not registered or missing `navItems`.
+
+**Fix**: Verify module is in `apps/web/src/modules.client.ts` and defines `navItems` in `defineKuckitClientModule()`.
+
 ## Related Documentation
 
 - [Kuckit SDK](https://github.com/draphonix/kuckit)

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

@@ -1,21 +1,20 @@
 import type { ModuleSpec } from '@kuckit/sdk'
-
-// Import your modules here
-// import { kuckitModule as itemsModule } from '@__APP_NAME_KEBAB__/items-module'
+import { kuckitModule as itemsModule } from '@__APP_NAME_KEBAB__/items-module'
 
 /**
  * Module specifications for the server application
  *
  * Add modules here to configure the server's functionality.
  * Modules are loaded in order, with dependencies resolved automatically.
+ *
+ * IMPORTANT: Server and client modules must be kept in sync!
+ * If you add/remove a module here, also update apps/web/src/modules.client.ts
  */
 export const getModuleSpecs = (): ModuleSpec[] => {
 	const modules: ModuleSpec[] = [
-		// Add your modules here:
-		// {
-		//   module: itemsModule,
-		//   config: { ... },
-		// },
+		// KUCKIT_SERVER_MODULES_START
+		{ module: itemsModule },
+		// KUCKIT_SERVER_MODULES_END
 	]
 
 	return modules

package/templates/base/apps/server/tsdown.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+	entry: './src/server.ts',
+	format: 'esm',
+	outDir: './dist',
+	clean: true,
+})

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

@@ -15,6 +15,7 @@
 		"@radix-ui/react-avatar": "^1.1.10",
 		"@radix-ui/react-collapsible": "^1.1.11",
 		"@radix-ui/react-dialog": "^1.1.14",
+		"@radix-ui/react-dropdown-menu": "^2.1.15",
 		"@radix-ui/react-separator": "^1.1.7",
 		"@radix-ui/react-slot": "^1.2.3",
 		"@radix-ui/react-tooltip": "^1.2.7",

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

@@ -65,6 +65,31 @@ export const itemsTable = pgTable('items', {
 
 The schema is imported by `drizzle.config.ts` for migration generation.
 
+### ⚠️ Important: Register Module Schemas
+
+**Drizzle only discovers schemas listed in `drizzle.config.ts`**. When adding a new module with database tables:
+
+1. Add the module's schema path to `drizzle.config.ts`:
+
+   ```typescript
+   export default defineConfig({
+   	schema: [
+   		resolve(currentDirPath, './src/schema'),
+   		// Add module schema paths here:
+   		resolve(currentDirPath, '../your-module/src/adapters/schema.drizzle.ts'),
+   	],
+   	// ...
+   })
+   ```
+
+2. Generate and apply migration:
+   ```bash
+   bun run db:generate
+   bun run db:migrate
+   ```
+
+**Common Issue**: If you see "relation does not exist" errors, the module schema likely isn't registered in `drizzle.config.ts`.
+
 ## Connection
 
 ```typescript

package/templates/base/packages/db/drizzle.config.ts

@@ -12,7 +12,11 @@ dotenv.config({
 })
 
 export default defineConfig({
-	schema: [resolve(currentDirPath, './src/schema')],
+	schema: [
+		resolve(currentDirPath, './src/schema'),
+		// Module schemas - add new module schema paths here
+		resolve(currentDirPath, '../items-module/src/adapters/item.drizzle.ts'),
+	],
 	out: resolve(currentDirPath, './src/migrations'),
 	dialect: 'postgresql',
 	dbCredentials: { url: buildDatabaseUrl() },

package/templates/base/packages/db/src/migrations/0000_init.sql

@@ -52,3 +52,13 @@ CREATE TABLE IF NOT EXISTS "verification" (
 
 ALTER TABLE "session" ADD CONSTRAINT "session_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;
 ALTER TABLE "account" ADD CONSTRAINT "account_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;
+
+-- Items module table
+CREATE TABLE IF NOT EXISTS "items" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"created_at" timestamp NOT NULL DEFAULT now(),
+	"updated_at" timestamp NOT NULL DEFAULT now(),
+	"user_id" text NOT NULL
+);