[WIP] Implement router inheritance and merging for nested routers (#3654)

Copilot · ardatan · web-flow · commit a313e10783e9 · 2026-03-23T11:33:59.000+03:00
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: ardatan &lt;20847995+ardatan@users.noreply.github.com&gt;
diff --git a/.changeset/router-composition.md b/.changeset/router-composition.md
@@ -0,0 +1,28 @@
+---
+'fets': minor
+---
+
+Add `use()` method for router composition and merging
+
+Routers can now be composed together using the `.use()` method, allowing you to split routes
+across multiple files and merge them into a parent router.
+
+```ts
+// users-router.ts
+const usersRouter = createRouter()
+  .route({ path: '/users', method: 'GET', handler: () => Response.json({ users: [] }) })
+
+// app.ts
+const app = createRouter()
+  .use(usersRouter)                 // merge at existing paths
+  .use('/api', anotherRouter)       // merge under a prefix
+```
+
+The `.use()` method supports:
+- Merging a sub-router at its existing paths
+- Merging with a path prefix
+- Sub-routers with their own `base` option
+- Transitive composition (a merged router can itself be merged)
+
+Internal routes (e.g. OpenAPI schema endpoint, Swagger UI) from sub-routers are not propagated
+to the parent router.
diff --git a/packages/fets/src/createRouter.ts b/packages/fets/src/createRouter.ts
@@ -85,6 +85,15 @@ export function createRouterBase(
       >
     >
   >();
+  const __routes: RouteWithSchemasOpts<
+    any,
+    RouterComponentsBase,
+    RouteSchemas,
+    HTTPMethod,
+    string,
+    TypedRequest,
+    TypedResponse
+  >[] = [];
 
   function handleUnhandledRoute(requestPath: string) {
     if (landingPage) {
@@ -226,6 +235,9 @@ export function createRouterBase(
         TypedResponse
       >,
     ) {
+      if (!route.internal) {
+        __routes.push(route);
+      }
       for (const onRouteHook of onRouteHooks) {
         onRouteHook({
           basePath,
@@ -238,8 +250,30 @@ export function createRouterBase(
       }
       return this as any;
     },
+    use(
+      prefixOrSubRouter: string | Router<any, any, any>,
+      subRouter?: Router<any, any, any>,
+    ) {
+      let prefix = '';
+      let actualSubRouter: Router<any, any, any>;
+      if (typeof prefixOrSubRouter === 'string') {
+        prefix = prefixOrSubRouter === '/' ? '' : prefixOrSubRouter;
+        actualSubRouter = subRouter!;
+      } else {
+        actualSubRouter = prefixOrSubRouter;
+      }
+      const subBase = actualSubRouter.__base === '/' ? '' : actualSubRouter.__base;
+      for (const subRoute of actualSubRouter.__routes) {
+        const subPath = subRoute.path === '/' ? '' : subRoute.path;
+        const newPath = `${prefix}${subBase}${subPath}` || '/';
+        this.route({ ...subRoute, path: newPath });
+      }
+      return this as any;
+    },
     __client: {},
     __onRouterInitHooks,
+    __routes,
+    __base: basePath,
   };
 }
 
diff --git a/packages/fets/src/types.ts b/packages/fets/src/types.ts
@@ -285,8 +285,42 @@ export interface RouterBaseObject<
     TComponents,
     TRouterSDK & RouterSDK<TPath, TTypedRequest, TTypedResponse>
   >;
+  use<
+    TSubServerContext,
+    TSubComponents extends RouterComponentsBase,
+    TSubRouterSDK extends RouterSDK<string, TypedRequest, TypedResponse>,
+  >(
+    subRouter: Router<TSubServerContext, TSubComponents, TSubRouterSDK>,
+  ): Router<TServerContext, TComponents, TRouterSDK & TSubRouterSDK>;
+  use<
+    const TPrefix extends string,
+    TSubServerContext,
+    TSubComponents extends RouterComponentsBase,
+    TSubRouterSDK extends RouterSDK<string, TypedRequest, TypedResponse>,
+  >(
+    prefix: TPrefix,
+    subRouter: Router<TSubServerContext, TSubComponents, TSubRouterSDK>,
+  ): Router<
+    TServerContext,
+    TComponents,
+    TRouterSDK & {
+      [TKey in keyof TSubRouterSDK as TKey extends string
+        ? `${TPrefix}${TKey}`
+        : TKey]: TSubRouterSDK[TKey];
+    }
+  >;
   __client: TRouterSDK;
   __onRouterInitHooks: OnRouterInitHook<TServerContext>[];
+  __routes: RouteWithSchemasOpts<
+    any,
+    RouterComponentsBase,
+    RouteSchemas,
+    HTTPMethod,
+    string,
+    TypedRequest,
+    TypedResponse
+  >[];
+  __base: string;
 }
 
 export type Router<
diff --git a/packages/fets/tests/router.spec.ts b/packages/fets/tests/router.spec.ts
@@ -207,4 +207,112 @@ describe('Router', () => {
     const json = await response.json();
     expect(json).toEqual({ foo: { bar: 'baz' } });
   });
+
+  describe('use() - router merging', () => {
+    it('merges a sub-router without prefix', async () => {
+      const usersRouter = createRouter<any, {}>().route({
+        path: '/users',
+        method: 'GET',
+        handler: () => Response.json({ users: ['alice', 'bob'] }),
+      });
+      const mainRouter = createRouter<any, {}>().use(usersRouter);
+      const response = await mainRouter.fetch('http://localhost:3000/users');
+      expect(response.status).toBe(200);
+      const json = await response.json();
+      expect(json.users).toEqual(['alice', 'bob']);
+    });
+
+    it('merges a sub-router with a prefix', async () => {
+      const usersRouter = createRouter<any, {}>().route({
+        path: '/users',
+        method: 'GET',
+        handler: () => Response.json({ users: ['alice', 'bob'] }),
+      });
+      const mainRouter = createRouter<any, {}>().use('/api', usersRouter);
+      const response = await mainRouter.fetch('http://localhost:3000/api/users');
+      expect(response.status).toBe(200);
+      const json = await response.json();
+      expect(json.users).toEqual(['alice', 'bob']);
+    });
+
+    it('merges a sub-router that has its own base path', async () => {
+      const usersRouter = createRouter<any, {}>({ base: '/users' }).route({
+        path: '/:id',
+        method: 'GET',
+        handler: request => Response.json({ id: request.params.id }),
+      });
+      const mainRouter = createRouter<any, {}>().use(usersRouter);
+      const response = await mainRouter.fetch('http://localhost:3000/users/42');
+      expect(response.status).toBe(200);
+      const json = await response.json();
+      expect(json.id).toBe('42');
+    });
+
+    it('merges multiple sub-routers', async () => {
+      const usersRouter = createRouter<any, {}>().route({
+        path: '/users',
+        method: 'GET',
+        handler: () => Response.json({ resource: 'users' }),
+      });
+      const postsRouter = createRouter<any, {}>().route({
+        path: '/posts',
+        method: 'GET',
+        handler: () => Response.json({ resource: 'posts' }),
+      });
+      const mainRouter = createRouter<any, {}>().use(usersRouter).use(postsRouter);
+      const usersResponse = await mainRouter.fetch('http://localhost:3000/users');
+      expect(usersResponse.status).toBe(200);
+      expect(await usersResponse.json()).toEqual({ resource: 'users' });
+      const postsResponse = await mainRouter.fetch('http://localhost:3000/posts');
+      expect(postsResponse.status).toBe(200);
+      expect(await postsResponse.json()).toEqual({ resource: 'posts' });
+    });
+
+    it('merges sub-router with prefix and route params', async () => {
+      const itemsRouter = createRouter<any, {}>().route({
+        path: '/:id',
+        method: 'GET',
+        handler: request => Response.json({ id: request.params.id }),
+      });
+      const mainRouter = createRouter<any, {}>().use('/items', itemsRouter);
+      const response = await mainRouter.fetch('http://localhost:3000/items/99');
+      expect(response.status).toBe(200);
+      const json = await response.json();
+      expect(json.id).toBe('99');
+    });
+
+    it('does not register sub-router internal routes in merged router', async () => {
+      const subRouter = createRouter<any, {}>({
+        openAPI: { endpoint: '/openapi.json' },
+      }).route({
+        path: '/hello',
+        method: 'GET',
+        handler: () => Response.json({ hello: 'world' }),
+      });
+      const mainRouter = createRouter<any, {}>().use('/sub', subRouter);
+      // The sub-router's internal /openapi.json should NOT be re-registered in the merged router
+      const mergedPaths = mainRouter.__routes.map((r: any) => r.path);
+      expect(mergedPaths).not.toContain('/sub/openapi.json');
+      // The user-defined route should be in __routes with the prefix applied
+      expect(mergedPaths).toContain('/sub/hello');
+      // The merged route should be accessible
+      const helloResponse = await mainRouter.fetch('http://localhost:3000/sub/hello');
+      expect(helloResponse.status).toBe(200);
+    });
+
+    it('handles transitive use() - router merged into another merged router', async () => {
+      const deepRouter = createRouter<any, {}>({ landingPage: false }).route({
+        path: '/deep',
+        method: 'GET',
+        handler: () => Response.json({ level: 'deep' }),
+      });
+      const midRouter = createRouter<any, {}>({ landingPage: false }).use('/mid', deepRouter);
+      const topRouter = createRouter<any, {}>({ landingPage: false }).use('/top', midRouter);
+
+      const response = await topRouter.fetch('http://localhost:3000/top/mid/deep');
+      expect(response.status).toBe(200);
+      const json = await response.json();
+      expect(json).toEqual({ level: 'deep' });
+    });
+  });
 });
diff --git a/website/src/pages/server/_meta.ts b/website/src/pages/server/_meta.ts
@@ -3,6 +3,7 @@ export default {
   'type-safety-and-validation': 'Type-Safety & Validation',
   'error-handling': 'Error Handling',
   'programmatic-schemas': 'Programmatic Schemas with TypeBox',
+  'router-composition': 'Router Composition',
   testing: 'Testing',
   cors: 'CORS',
   cookies: 'Cookies',
diff --git a/website/src/pages/server/router-composition.mdx b/website/src/pages/server/router-composition.mdx
