Lambda DevKit

A development toolkit for compiling and running AWS Lambda functions locally with API Gateway simulation.

Features

• Local Execution: Run your AWS Lambda functions locally without deploying to AWS.
• API Gateway Simulation: Simulate API Gateway routes and methods (e.g., GET, POST, PUT, DELETE).
• Compilation Support: Automatically compile TypeScript or JavaScript Lambda functions.
• Flexible Configuration: Define routes, handlers, and environment variables in a simple configuration file.
• Developer-Friendly CLI: Use the ldk command to manage and test your Lambda functions.

Installation

Install the package as a project dependency:

pnpm add @nexckycort/lambda-devkit -D

Quick Start

1. Create a Configuration File
   Create a file named lambda-devkit.config.ts in the root of your project. Here's an example configuration:

import type { LambdaDevkitConfig } from '@nexckycort/lambda-devkit';

const config: LambdaDevkitConfig = {
  server: {
    routes: [
      {
        method: 'GET',
        path: 'users',
        lambda: {
          handler: 'functions/getUsers',
          timeout: 5000,
        },
      },
      {
        method: 'POST',
        path: 'users',
        lambda: {
          handler: 'functions/createUser',
          timeout: 10000,
        },
      },
    ],
    port: 4000,
    environment: {
      ENV: 'dev',
    },
  },
  build: {
    bundle: true,
    minify: true,
    external: ['@aws-sdk/*'],
  },
};

export default config;

2. Start the Local Server
   Run the following command to start the local server:

   ldk dev

3. Test Your Endpoints
   Use tools like Postman or curl to test your endpoints:

   curl http://localhost:4000/users

Usage

Commands

The ldk CLI provides the following commands:

| Command | Description | |------------------|-----------------------------------------------------| | ldk dev | Start the local server with API Gateway simulation. | | ldk build | Compile your Lambda functions. |

Example

Here’s an example of how to use the CLI:

# Build your Lambda functions
ldk build

# Start the local server
ldk dev

Configuration

Lambda DevKit uses a configuration file (lambda-devkit.config.ts) to define routes, handlers, and other settings. Below is a detailed explanation of each field:

server

Server configuration for local development.

| Field | Type | Description | |---------------|------------------|-----------------------------------------------------------------------------| | routes | RouteConfig[] | List of routes and their configurations. | | port | number | Port on which the local server will run. Default: 4000. | | environment | object | Environment variables to be passed to the Lambda function. |

routes

An array of route configurations. Each route maps an HTTP method and path to a Lambda function.

| Field | Type | Description | |---------------|------------------|-----------------------------------------------------------------------------| | method | string | HTTP method (e.g., GET, POST, PUT, DELETE). | | path | string | Path for the route. Supports wildcards like users/*. | | lambda | LambdaConfig | Configuration for the Lambda function that handles requests to this route. |

lambda

Configuration for a Lambda function.

| Field | Type | Description | |---------------|------------------|-----------------------------------------------------------------------------| | handler | string | Path to the folder containing the Lambda handler (e.g., functions/myFunction). | | timeout | number | Maximum execution time for the Lambda function in milliseconds. |

build

Build configuration for the Lambda functions.

| Field | Type | Description | |---------------|------------------|-----------------------------------------------------------------------------| | entryPoint | string | Entry point for the build process. Default: "functions/**". | | bundle | boolean | Whether to bundle the Lambda function code into a single file. | | minify | boolean | Whether to minify the Lambda function code during the build process. | | sourcemap | boolean \| string | Sourcemap generation options (true, 'linked', 'inline', etc.). | | outbase | string | Base directory for resolving entry points. Default: "functions". | | external | string[] | External libraries that should be excluded from the build. Default: ["@aws-sdk/*"]. |

Examples

Basic Example

Here’s a simple example of a Lambda function and its configuration:

src/getUsers/index.ts

export const handler = async (event: any) => {
  console.log("Event:", event);

  return {
    statusCode: 200,
    body: JSON.stringify([
      { id: 1, name: "Alice" },
      { id: 2, name: "Bob" },
    ]),
  };
};

lambda-devkit.config.ts

import type { LambdaDevkitConfig } from '@nexckycort/lambda-devkit';

const config: LambdaDevkitConfig = {
  server: {
    routes: [
      {
        method: 'GET',
        path: 'users',
        lambda: {
          handler: 'functions/getUsers'
        },
      },
    ],
    port: 4000,
  },
  build: {
    bundle: true,
    minify: true,
    external: ['@aws-sdk/*'],
  },
};

export default config;

Run the server:

ldk dev

Test the endpoint:

curl http://localhost:4000/users

License

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