Feature request: Split routes with Router - includeRouter method

[dreamorosi]

Use case

As applications grow and the number of routes a Lambda function handles increases, it becomes natural to either break into smaller Lambda functions or split routes into separate files to ease maintenance.

Currently, the TypeScript event-handler's Router class doesn't provide a way to compose multiple router instances, forcing developers to define all routes in a single file or manually merge route definitions.

This creates several challenges:

• Maintainability: Large route files become difficult to manage and navigate
• Team collaboration: Multiple developers working on different route groups can create merge conflicts
• Code organization: Related routes cannot be logically grouped in separate modules
• Reusability: Common route patterns cannot be easily shared across different Lambda functions

Solution/User Experience

Implement an includeRouter method on the Router class that allows merging routes, context, and middleware from one router instance into another. This would mirror the functionality available in the Python version of Powertools for AWS.

Basic usage

routes/todos.ts (separate route module):

import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';

export const router = new Router();

const endpoint = 'https://jsonplaceholder.typicode.com/todos';

router.get('/todos', async (_, { request }) => {
  const apiKey = request.headers['x-api-key'];
  
  const response = await fetch(endpoint, {
    headers: { 'X-Api-Key': apiKey }
  });
  const todos = await response.json();
  
  return { todos: todos.slice(0, 10) };
});

router.get('/todos/{todoId}', async ({ todoId }, { request }) => {
  const apiKey = request.headers['x-api-key'];
  
  const response = await fetch(`${endpoint}/${encodeURIComponent(todoId)}`, {
    headers: { 'X-Api-Key': apiKey }
  });
  const todo = await response.json();
  
  return { todo };
});

handler.ts (main Lambda handler):

import { router as todosRouter } from './routes/todos.js';
import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda';

const logger = new Logger();
const app = new Router({ logger });

// Include routes from separate module
app.includeRouter(todosRouter);

export const handler = async (event: unknown, context: Context) => {
  logger.addContext(context);
  return app.resolve(event, context);
};

Route prefix support

Allow prefixing routes when including a router to avoid repetitive path definitions:

// Remove '/todos' prefix from route definitions
router.get('/', async (_, { request }) => { /* get all todos */ });
router.get('/{todoId}', async ({ todoId }, { request }) => { /* get specific todo */ });

// Include with prefix
app.includeRouter(todosRouter, { prefix: '/todos' });

Context sharing with appendContext

Support sharing contextual data between router instances:

export const handler = async (event: unknown, context: Context) => {
  app.appendContext({ isAdmin: true, userId: 'user123' });
  return app.resolve(event, context);
};

Routes in included routers can access this context:

router.get('/todos', async (_, { request, reqCtx }) => {
  const isAdmin = context.get('isAdmin', false);
  // Use context in route logic
});

Method signature

class Router {
  includeRouter(router: Router, options?: { prefix?: string }): void;
  appendContext(data: Record<string, unknown>): void;
}

Alternative solutions

N/A

Open questions

The appendContext method allows adding arbitrary key-value pairs to the context.

This is not the Lambda function's context object but a shared request-specific context - hence the suggested reqCtx name.

Is this clear enough, or should we consider a different name? Should we also rename the context property currently used in the RequestContext to something like lambdaContext to avoid confusion?

Should we instead add the context directly to the RequestContext object, making it accessible in route handlers as:

router.get('/todos', async (_, { isAdmin }) => {});

And if we do this, how do we handle potential naming conflicts with existing properties?

Also, I want to make sure this context is future proof in case as I want to make it easier to surface the context from Lambda Authorizers that is currently buried in the request.requestContext.authorizer property.

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[leandrodamascena]

This is a nit pick and might a overzealous on my part, but I find the experience very confusing when you include a router object inside another router object. Should it be Resolver the top level entity and Router the specific router entity?

Just ignore if doesn't make sense.

[dreamorosi]

We don't have a Resolver class like in Python, everything is a Router here.

With this feature we're basically just merging routers - which part do you find confusing?

Also, besides the name, what's the difference between a Resolver and a Router?

[leandrodamascena]

That's my point. I think a Resolver is the top-level entity, where you can configure CORS, OpenAPI, Compress, Data Validation, Schemas, and more. The Router is a specific object that deals objectively with routes. The Resolver should inherit the route and implement the same methods, but the Resolver should have different responsibilities.

I may be biased towards Python's implementation, but the following experience is very confusing to me:

import { router as todosRouter } from './routes/todos.js';
import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda';

const logger = new Logger();
const router = new Router({ logger }); // router?

// Include routes from separate module
router.includeRouter(todosRouter); // include router in router?

router.enableSwagger() // Enable swagger in a router?
router.OpenAPI... // Enable OpenAPI in a router?
router.compress // I'm enabling compress in a router or in all routes?

export const handler = async (event: unknown, context: Context) => {
  logger.addContext(context);
  return app.resolve(event, context);
};

I think it's super confusing that the same object name/constructor name/whatever name does all the things. But again, I don't have strong opinions on this, and go with the implementation that makes the most sense to you.

[dreamorosi]

Fair.

I don't find it confusing but I'm open to discuss this and change it, if we think it's good for feature parity.

Personally the distinction between Resolver and Router seems arbitrary, in practice they do the same thing which is get an event, route/resolve it, and return a response.

I can see how coming from the Python implementation having a single Router class can be confusing, but besides being opinionated (which is good, don't get me wrong) I still don't get the why behind their hierarchy and why we need this separation of responsibility.

Specific features like OpenAPI, SwaggerUI, and dev mode among others are meant to global, so we'll accept them in the constructor. Everything else like CORS, compress, and other things that can be both global and route-specific will be available via middleware, which customers can place where they want (see how in the docs).

These distinctions - at least in my mental model - hold true regardless of having Resolver+Router or just Router.

I'd also like to hear @svozza's take on this, since he's done all the implementation and he's had the thought process the led to this (which I agreed with).

Like I said, at the moment the only reason to change it for me would be feature parity & consistency - which can be enough of a reason, really - but let's acknowledge that it's just an arbitrary naming that sounds familiar because it was implemented that way in the reference implementation.

[leandrodamascena]

Yes, I agree that this is an arbitrary name and probably no one in the world is using the Resolver nomenclature - probably only Powertools for AWS Python and TS are using this. I see that in some utilities, the PT TypeScript is using AppSyncEventsResolver, AppSyncGraphQLResolver and adding support for includeRouter with Router object, and BedrockAgentFunctionResolver.

There seems to be a discrepancy in this specific utility nomenclature here, which could be confusing for users. But again, you and @svozza can decide what you think is most appropriate.

[dreamorosi]

That's a good point, we did name the others Resolver, so we should probably be consistent.

Still keen on hearing @svozza though, let's wait for next week to make a decision.