feat(aurora): add support for custom tRPC routers with type safety (#1045)

* feat(aurora): add support for custom tRPC routers with type safety

- Export generic type helpers (CreateTypedTrpcReact, CreateTypedTrpcClient) for apps to extend tRPC clients with custom routers
- Export AuroraRouterWithCustom type helper for merging custom routers with base router
- Add trpcClient.ts to vite dts plugin include list to generate proper type definitions
- Export TrpcReact type from client index

This enables consuming apps (like dashboard) to:
1. Define custom tRPC routers using auroraRouter/protectedProcedure
2. Register them with createServer({ routers: [...] })
3. Re-export Aurora's tRPC clients with extended types for full type safety

* chore(aurora): remove unnedeed deps

* chore(aurora): bugfix in comments

* chore: exclude apps/dev from workspace and git tracking

- Add apps/dev/ to .gitignore (local testing only)
- Add !apps/dev to pnpm-workspace.yaml to exclude from workspace

* chore(changeset): add changeset for custom routers support

Author: andypf

.changeset/custom-routers-support.md

@@ -0,0 +1,47 @@
+---
+"@cobaltcore-dev/aurora": minor
+---
+
+Add support for custom tRPC routers with full type safety
+
+**New exports from `@cobaltcore-dev/aurora/server`:**
+- `AuroraRouterWithCustom<T>` - Type helper to merge custom routers with base Aurora router
+
+**New exports from `@cobaltcore-dev/aurora/client`:**
+- `CreateTypedTrpcReact<T>` - Generic type for typed React tRPC client
+- `CreateTypedTrpcClient<T>` - Generic type for typed vanilla tRPC client
+- `TrpcReact` - Type alias for the React tRPC client
+
+**Usage:**
+
+1. Define custom routers using `auroraRouter` and `protectedProcedure`:
+```typescript
+import { auroraRouter, protectedProcedure } from "@cobaltcore-dev/aurora/server"
+
+export const customRouters = auroraRouter({
+  feedback: auroraRouter({
+    submit: protectedProcedure
+      .input(z.object({ message: z.string() }))
+      .mutation(async ({ input }) => ({ success: true })),
+  }),
+})
+```
+
+2. Register with `createServer`:
+```typescript
+createServer({ routers: [customRouters], ... })
+```
+
+3. Create typed client exports:
+```typescript
+import type { AuroraRouterWithCustom } from "@cobaltcore-dev/aurora/server"
+import { trpcReact, CreateTypedTrpcReact } from "@cobaltcore-dev/aurora/client"
+
+type AppRouter = AuroraRouterWithCustom<typeof customRouters>
+export const trpc = trpcReact as unknown as CreateTypedTrpcReact<AppRouter>
+```
+
+4. Use with full type safety:
+```typescript
+const mutation = trpc.feedback.submit.useMutation() // ✅ Type-safe!
+```

.gitignore

@@ -20,3 +20,6 @@ test-results/
 playwright-results/
 playwright-report/
 playwright/.cache/
+
+# Dev app (local testing only)
+apps/dev/

packages/aurora/src/client/index.ts

@@ -6,4 +6,12 @@ export {
   type TrackEventPayload,
   type OnTrackEventCallback,
 } from "./AuroraApp"
-export { type TrpcClient, trpcClient, trpcReactClient, trpcReact } from "./trpcClient"
+export {
+  type TrpcClient,
+  type TrpcReact,
+  type CreateTypedTrpcReact,
+  type CreateTypedTrpcClient,
+  trpcClient,
+  trpcReactClient,
+  trpcReact,
+} from "./trpcClient"

packages/aurora/src/client/trpcClient.ts

@@ -1,6 +1,7 @@
 import { createTRPCReact } from "@trpc/react-query"
+import type { CreateTRPCReact } from "@trpc/react-query"
+import { createTRPCClient, type TRPCClient } from "@trpc/client"
 import {
-  createTRPCClient,
   httpBatchLink,
   httpBatchStreamLink,
   httpLink,
@@ -10,6 +11,18 @@ import {
 } from "@trpc/client"
 import type { AuroraRouter } from "../server/routers"
 
+/** Type alias for the React tRPC client */
+export type TrpcReact = ReturnType<typeof createTRPCReact<AuroraRouter>>
+
+/** Type alias for the vanilla tRPC client */
+export type TrpcClient = ReturnType<typeof createTRPCClient<AuroraRouter>>
+
+/** Generic type for creating a typed React tRPC client with a custom router */
+export type CreateTypedTrpcReact<TRouter extends AuroraRouter> = CreateTRPCReact<TRouter, unknown>
+
+/** Generic type for creating a typed vanilla tRPC client with a custom router */
+export type CreateTypedTrpcClient<TRouter extends AuroraRouter> = TRPCClient<TRouter>
+
 // CSRF headers factory
 const getCsrfHeaders = async () => {
   try {
@@ -91,10 +104,10 @@ const getLinks = () => [
 ]
 
 // React Query client (for hooks like useQuery/useMutation/useSubscription)
-export const trpcReact: ReturnType<typeof createTRPCReact<AuroraRouter>> = createTRPCReact<AuroraRouter>()
+export const trpcReact: TrpcReact = createTRPCReact<AuroraRouter>()
 
 let _trpcReactClient: ReturnType<typeof trpcReact.createClient> | null = null
-let _trpcClient: ReturnType<typeof createTRPCClient<AuroraRouter>> | null = null
+let _trpcClient: TrpcClient | null = null
 
 // Lazily initialised — created on first access after setBffEndpoint() has been called by App.
 export const trpcReactClient = new Proxy({} as ReturnType<typeof trpcReact.createClient>, {
@@ -106,14 +119,11 @@ export const trpcReactClient = new Proxy({} as ReturnType<typeof trpcReact.creat
   },
 })
 
-export const trpcClient = new Proxy({} as ReturnType<typeof createTRPCClient<AuroraRouter>>, {
+export const trpcClient: TrpcClient = new Proxy({} as TrpcClient, {
   get(_target, prop) {
     if (!_trpcClient) {
       _trpcClient = createTRPCClient<AuroraRouter>({ links: getLinks() })
     }
     return (_trpcClient as Record<string | symbol, unknown>)[prop]
   },
 })
-
-export type TrpcReact = typeof trpcReact
-export type TrpcClient = typeof trpcClient

packages/aurora/src/server/index.ts

@@ -9,3 +9,4 @@ export {
   projectScopedInputSchema,
   domainScopedInputSchema,
 } from "./trpc"
+export type { AuroraRouter, AuroraRouterWithCustom } from "./routers"

packages/aurora/src/server/routers.ts

@@ -19,7 +19,28 @@ const buildBaseRouter = (policyDir: string) =>
 
 export type AuroraRouter = ReturnType<typeof buildBaseRouter>
 
-export const buildAppRouter = (policyDir: string, extraRouters: AnyRouter[] = []): AuroraRouter => {
+/**
+ * Helper type to merge custom routers with the base Aurora router.
+ * Use this in consuming apps to create a properly typed router that includes custom routers.
+ *
+ * @example
+ * ```ts
+ * import type { AuroraRouterWithCustom } from "@cobaltcore-dev/aurora/server"
+ * import { customRouters } from "./server/customRouters"
+ *
+ * export type AppRouter = AuroraRouterWithCustom<typeof customRouters>
+ * ```
+ */
+export type AuroraRouterWithCustom<TCustomRouters extends AnyRouter> = AuroraRouter & TCustomRouters
+
+/**
+ * Builds the complete app router by merging Aurora's base routers with optional custom routers.
+ *
+ * @param policyDir - Directory containing policy files
+ * @param extraRouters - Optional array of custom tRPC routers to merge with base Aurora routers
+ * @returns The merged router (base routers + custom routers)
+ */
+export const buildAppRouter = (policyDir: string, extraRouters: AnyRouter[] = []) => {
   if (extraRouters.length === 0) return buildBaseRouter(policyDir)
-  return mergeRouters(buildBaseRouter(policyDir), ...extraRouters) as unknown as AuroraRouter
+  return mergeRouters(buildBaseRouter(policyDir), ...extraRouters)
 }

packages/aurora/vite.config.mjs

@@ -65,7 +65,7 @@ export default defineConfig(({ mode }) => {
       tsconfigPaths(),
       isLib &&
         dts({
-          include: ["index.ts", "AuroraApp.tsx"],
+          include: ["index.ts", "AuroraApp.tsx", "trpcClient.ts"],
           outDir: "../../dist/client",
           tsconfigPath: "../../tsconfig.json",
           entryRoot: ".",

pnpm-workspace.yaml

@@ -1,5 +1,6 @@
 packages:
   - "apps/*"
+  - "!apps/dev"
   - "packages/*"
 
 minimumReleaseAge: 10080