AWS CDK

The aws-cdk plugin generates AWS CDK helpers from your Typeweaver spec so you can register API Gateway HTTP API routes without manually repeating paths and methods in your stack.

It does not deploy your API by itself. Instead, it gives your CDK app a contract-aware route list that stays aligned with the generated output.

At the moment, this plugin targets API Gateway HTTP API (v2).

Generate the CDK helpers

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins aws-cdk

You can combine it with other plugins in the same run when your app also needs generated clients or server code:

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients,server,aws-cdk

What gets generated

For each resource, Typeweaver generates one file:

<ResourceName>HttpApiRoutes.ts

For a todo resource, that becomes:

TodoHttpApiRoutes

That class exposes getRoutes(), which returns the HTTP API route definitions for that resource.

How to use `getRoutes()` in a stack

import { Construct } from "constructs";
import { HttpApi } from "aws-cdk-lib/aws-apigatewayv2";
import { HttpLambdaIntegration } from "aws-cdk-lib/aws-apigatewayv2-integrations";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import { TodoHttpApiRoutes } from "./api/generated";

type TodoApiProps = {
  readonly httpApi: HttpApi;
};

export class TodoApi extends Construct {
  public constructor(scope: Construct, id: string, props: TodoApiProps) {
    super(scope, id);

    const handler = new NodejsFunction(this, "Handler", {
      entry: "./src/todo-handler.ts",
    });

    const integration = new HttpLambdaIntegration("TodoIntegration", handler);

    for (const route of new TodoHttpApiRoutes().getRoutes()) {
      props.httpApi.addRoutes({
        integration,
        path: route.path,
        methods: route.methods,
      });
    }
  }
}

What `getRoutes()` gives you

getRoutes() returns the route metadata already derived from your spec:

the API path
the allowed HTTP methods
path parameters converted to HTTP API format

For example, a Typeweaver path like /todos/:todoId becomes /todos/{todoId} for API Gateway HTTP API.

Where this fits in your workflow

The usual flow is:

update the Typeweaver spec
run typeweaver generate
synthesize or deploy your CDK app

That keeps the contract and your infrastructure route registration in sync.

What this plugin does not do

Keep expectations narrow:

it does not generate a full CDK app
it does not create Lambda functions for you
it does not configure REST API v1 resources
it is currently for HTTP API v2 only

You still decide which integrations, authorizers, domains, stages, and deployment topology your stack should use.

A practical pattern

A common setup is:

server or hono plugin for runtime handlers
aws-cdk plugin for route registration
one Lambda per resource or one shared Lambda, depending on your app

Typeweaver stays responsible for the contract. CDK stays responsible for the infrastructure.