CdkLess: Ultra-Simplified Serverless Microservices Framework

The simplest way to build serverless microservices with AWS CDK

CdkLess dramatically simplifies the development of serverless microservices on AWS by providing a clean, intuitive API that abstracts away the complexities of the AWS Cloud Development Kit (CDK).

⚠️ Beta Status

CdkLess is currently in beta. While it's functional and usable, please be aware of the following:

• The API may change without following strict semantic versioning until v1.0
• Some features are still in development
• Documentation might be incomplete in some areas
• Use in production environments at your own risk
• We welcome feedback, bug reports, and contributions to help stabilize the library

We're actively working to reach a stable 1.0 release and appreciate your understanding and support during this beta phase.

🚀 Installation

npm install cdkless aws-cdk-lib constructs

🎯 Why CdkLess?

CdkLess was created for development teams that need to:

• Build and deploy microservices quickly without deep AWS expertise
• Maintain consistent infrastructure patterns across multiple services
• Focus on business logic rather than infrastructure code
• Follow best practices without having to reinvent them each time

📊 Comparison with Standard CDK

📋 Quick Start

Create a fully functional serverless microservice in just one file:

// src/app.ts
import { CdkLess } from 'cdkless';

const app = new CdkLess("user-services");
app.lambda('src/handlers/users/get-users')
   .get('/users');

app.lambda('src/handlers/users/create-user')
    .post('/users');

app.lambda('src/handlers/users/delete-user')
    .delete('/users');

app.lambda('src/handlers/users/update-user')
    .put('/users');

// That's it! Just instantiate your microservice

🏛️ Architectural Approach

CdkLess follows a specific architectural pattern:

• Infrastructure Separation: The library is designed with the convention that infrastructure (databases, queues, topics, etc.) is managed in a separate CDK project. This separation of concerns allows infrastructure teams to maintain core resources independently.

• Service Integration: CdkLess focuses specifically on mounting API Gateway endpoints, Lambda functions, and their triggers by importing existing resources via ARNs. This approach encourages a clean separation between infrastructure and application code.

• ARN-Based Integration: Instead of creating infrastructure resources directly, CdkLess connects to existing resources using their ARNs. This pattern promotes infrastructure reuse and better governance of cloud resources.

// Example of connecting to existing infrastructure via ARNs
app.lambda("src/handlers/orders/process")
  .post("/orders")
  .addTablePermissions("arn:aws:dynamodb:region:account:table/orders-table") // Connect to existing DynamoDB table
  .addSnsTrigger("arn:aws:sns:region:account:topic/order-events"); // Connect to existing SNS topic

🔍 Key Features

🌐 API Gateway Integration

Create HTTP API endpoints with a fluent interface:

// GET endpoint
app.lambda("src/handlers/products/get-product").get("/products/:id");

// POST endpoint
app.lambda("src/handlers/products/create-product").post("/products");

// PUT endpoint
app.lambda("src/handlers/products/update-product").put("/products/:id");

// DELETE endpoint
app.lambda("src/handlers/products/delete-product").delete("/products/:id");

🔐 API Authorization

Secure your endpoints with various types of authorizers:

import {
  HttpJwtAuthorizer,
  HttpLambdaAuthorizer,
} from "aws-cdk-lib/aws-apigatewayv2-authorizers";
import { Function } from "aws-cdk-lib/aws-lambda";

// Creating a Lambda authorizer
const authorizerFunction = new Function(this, "AuthorizerFunction", {
  // function configuration
});

const lambdaAuthorizer = new HttpLambdaAuthorizer(
  "my-lambda-authorizer",
  authorizerFunction,
  {
    authorizerName: "my-lambda-authorizer",
    identitySource: ["$request.header.Authorization"],
  }
);

// Creating a JWT authorizer
const jwtAuthorizer = new HttpJwtAuthorizer(
  "my-jwt-authorizer",
  "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX",
  {
    jwtAudience: ["my-app-client-id"],
  }
);

// Securing routes with authorizers
app.lambda("src/handlers/admin/dashboard")
  .get("/admin/dashboard")
  .addAuthorizer(lambdaAuthorizer);

app.lambda("src/handlers/users/profile")
  .get("/users/profile")
  .addAuthorizer(jwtAuthorizer, ["profile:read"]);

📊 Database Integration

Connect to DynamoDB tables using ARNs:

app.lambda("src/handlers/orders/create-order")
  .post("/orders")
  .addTablePermissions("arn:aws:dynamodb:region:account:table/orders-table");

📨 Event-Driven Architecture

Create event-driven microservices with SQS, SNS, and S3 triggers:

// SQS Queue consumer
app.lambda("src/handlers/orders/process-order").addSqsTrigger(
  "arn:aws:sqs:region:account:queue/orders-queue"
);

// SNS Topic subscriber
app.lambda("src/handlers/notifications/send-email").addSnsTrigger(
  "arn:aws:sns:region:account:topic/notifications-topic"
);

// S3 event handler
app.lambda("src/handlers/documents/process-upload").addS3Trigger(
  "arn:aws:s3:region:account:bucket/documents-bucket"
);

⚙️ Environment Configuration

Add environment variables to your Lambda functions:

app.lambda("src/handlers/payment/process").post("/payments").environment({
  PAYMENT_API_KEY: "secret-key",
  STAGE: this.stage,
  LOG_LEVEL: "INFO",
});

By default, CdkLess uses the STAGE environment variable to determine the deployment stage (e.g., 'dev', 'staging', 'prod'). If not set, it defaults to 'dev'.

🏗️ Microservice Architecture Best Practices

CdkLess encourages microservice best practices:

1. Single Responsibility Principle

Each Lambda function should handle a specific task. For example:

// User service
app.lambda("src/handlers/users/get-user").get("/users/:id");
app.lambda("src/handlers/users/create-user").post("/users");
app.lambda("src/handlers/users/update-user").put("/users/:id");
app.lambda("src/handlers/users/delete-user").delete("/users/:id");

// Order service
app.lambda("src/handlers/orders/get-order").get("/orders/:id");
app.lambda("src/handlers/orders/create-order").post("/orders");

2. Domain-Driven Design

Organize your handlers by domain:

src/
  handlers/
    users/
      get-user.ts
      create-user.ts
    orders/
      get-order.ts
      create-order.ts
    payments/
      process-payment.ts

3. Shared Resources

Resources are shared automatically. For example, all HTTP endpoints will share a single API Gateway.

📄 API Reference

For detailed API documentation, please visit our API Reference page.

🌟 Core Principles

CdkLess is built on these core principles:

1. Everything in One Place: Define, configure, and deploy from a single file
2. Fluent API: Chain methods for intuitive Lambda configuration
3. Convention Over Configuration: Sensible defaults for everything
4. Automatic Building: No need to call .build() or .synth()
5. Minimal Magic: No hidden configuration
6. Encapsulated Dependencies: The framework handles all CDK dependencies

🤔 FAQ

How does CdkLess compare to other frameworks like Serverless Framework?

CdkLess builds directly on top of AWS CDK, giving you the full power of CDK with a simplified interface. Unlike configuration-based frameworks, CdkLess uses a code-first approach, which provides greater flexibility and type safety.

Can I access the underlying CDK constructs?

Yes, CdkLess doesn't hide the underlying CDK. You can always access the shared API or other resources.

How does deployment work?

CdkLess handles the CDK synthesis process automatically when your application runs. Just execute your application with npm start and it will deploy to AWS.

What does the beta status mean for my project?

During the beta phase, we recommend using CdkLess for non-critical projects, proofs of concept, or in environments where you can tolerate potential API changes. We're working hard to stabilize the API for a 1.0 release, but until then, you should expect possible breaking changes between minor versions. We recommend pinning to exact versions in your package.json during the beta period.

📋 Requirements

• Node.js 22+
• AWS CLI configured
• AWS CDK CLI (npm install -g aws-cdk)

🙏 Contributing

We welcome contributions! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Resource Visualization

CdkLess provides an elegant way to visualize deployed resources with a beautiful format in the terminal. This functionality is directly integrated into the framework and is automatically activated during deployment.

Visualization Features

When you deploy a stack with CDKless, you'll automatically see a detailed summary of all deployed resources:

• 🚀 Stack and stage summary
• 📊 Resource count by type (Lambdas, API endpoints, SNS Topics, etc.)
• 🌐 API Gateway URL
• ⚡ Details of each Lambda function:
  • Configuration (memory, timeout)
  • Environment variables
  • Configured triggers

This visual format makes it much easier to understand which resources have been deployed and how they are configured.