@lafken/main

Core entry point for a Lafken serverless application. @lafken/main initializes the AWS provider, orchestrates resolvers and modules, and synthesizes the resulting Terraform configuration through CDKTN. It provides createApp to bootstrap the application and createModule to organize resources into logical groups.

Installation

npm install @lafken/main

Getting Started

Create an application with resolvers and modules, then let Lafken generate all the infrastructure:

import { createApp, createModule } from '@lafken/main';
import { ApiResolver } from '@lafken/api/resolver';
import { QueueResolver } from '@lafken/queue/resolver';

// 1. Define modules that group related resources
const userModule = createModule({
  name: 'users',
  resources: [UserApi, UserQueue],
});

const billingModule = createModule({
  name: 'billing',
  resources: [InvoiceSchedule],
});

// 2. Create the application
await createApp({
  name: 'my-app',
  modules: [userModule, billingModule],
  resolvers: [
    new ApiResolver({ restApi: { name: 'my-api' } }),
    new QueueResolver(),
  ],
});

Features

createApp

createApp is the main entry point. It initializes the AWS stack, runs all resolver lifecycle hooks (beforeCreate → create → afterCreate), and synthesizes the Terraform output:

await createApp({
  name: 'my-app',
  modules: [userModule, billingModule],
  resolvers: [new ApiResolver(), new QueueResolver()],
  globalConfig: {
    lambda: {
      memory: 512,
      timeout: 30,
      runtime: 22,
      services: ['dynamodb', 's3', 'sqs'],
    },
    tags: {
      environment: 'production',
      team: 'platform',
    },
  },
  awsProviderConfig: {
    region: 'us-east-1',
    profile: 'my-aws-profile',
  },
  s3Backend: {
    bucket: 'my-terraform-state',
    key: 'app/terraform.tfstate',
    region: 'us-east-1',
  },
  extend: async (scope) => {
    // Add custom CDKTN constructs after all resolvers finish
  },
});

Application Options

| Option | Type | Required | Description | | ------------------- | ------------------- | -------- | --------------------------------------------------------- | | name | string | Yes | Application name, used as the stack identifier | | modules | StackModule[] | Yes | Modules created with createModule | | resolvers | ResolverType[] | Yes | Resolvers that process decorated resources | | globalConfig | GlobalConfig | No | Shared Lambda and tag settings for all resources | | awsProviderConfig | AwsProviderConfig | No | AWS provider settings (region, profile, etc.) | | s3Backend | S3BackendConfig | No | Remote S3 backend for Terraform state | | extend | (scope) => void | No | Callback invoked after all resolvers finish |

createModule

createModule groups related resources into a logical unit with its own scope, IAM role, and configuration. Each resource inside the module is processed by the matching resolver based on its decorator type:

const orderModule = createModule({
  name: 'orders',
  resources: [OrderApi, OrderQueue, OrderSchedule],
  globalConfig: {
    lambda: {
      memory: 256,
      timeout: 15,
      services: ['dynamodb', 'sqs'],
    },
    tags: {
      domain: 'orders',
    },
  },
});

Module Options

| Option | Type | Required | Description | | -------------- | ----------------- | -------- | ----------------------------------------------------- | | name | string | Yes | Module name, used as scope and tag identifier | | resources | ClassResource[] | Yes | Decorated classes to be processed by resolvers | | globalConfig | GlobalConfig | No | Lambda and tag settings scoped to this module |

Global Configuration

Global configuration applies default settings to all Lambda functions and resources. Values cascade from application to module to individual resource, with more specific settings taking precedence:

App globalConfig → Module globalConfig → Resource-level config

Lambda Configuration

| Option | Type | Description | | ------------- | ---------------- | --------------------------------------------------------- | | memory | number | Memory allocation in MB | | timeout | number | Execution timeout in seconds | | runtime | 20 \| 22 \| 24 | Node.js runtime version | | services | Services[] | AWS services the Lambda can access (creates IAM role) | | enableTrace | boolean | Enable AWS X-Ray tracing | | env | EnvironmentValue | Environment variables for Lambda functions |

Available Services

Services define which AWS resources the Lambda IAM role can access:

| Service | Description | | --------------- | -------------------------------- | | dynamodb | Amazon DynamoDB | | s3 | Amazon S3 | | lambda | AWS Lambda | | cloudwatch | Amazon CloudWatch Logs | | sqs | Amazon SQS | | state_machine | AWS Step Functions | | kms | AWS KMS | | ssm | AWS Systems Manager Parameter Store | | event | Amazon EventBridge |

For fine-grained control, specify individual permissions:

services: [
  'cloudwatch',
  { type: 'dynamodb', permissions: ['Query', 'GetItem'] },
  { type: 's3', permissions: ['GetObject'], resources: ['arn:aws:s3:::my-bucket/*'] },
  { type: 'custom', serviceName: 'ses', permissions: ['SendEmail'] },
]

Tags

Tags are applied automatically to all taggable resources. Module-level tags merge with app-level tags, and resource-specific tags take highest precedence:

// App-level tags
globalConfig: {
  tags: {
    environment: 'production',
    project: 'my-app',
  },
}

// Module-level tags (merged with app tags)
globalConfig: {
  tags: {
    domain: 'orders',
  },
}

Lafken also adds automatic tags: lafken:app with the app name and lafken:module with the module name.

S3 Backend

Store Terraform state remotely in an S3 bucket for team collaboration and state locking:

await createApp({
  name: 'my-app',
  s3Backend: {
    bucket: 'terraform-state-bucket',
    key: 'apps/my-app/terraform.tfstate',
    region: 'us-east-1',
    dynamodbTable: 'terraform-locks',
  },
});

Extending the Application

The extend callback runs after all resolvers have finished processing. Use it to add custom infrastructure that is not covered by the standard resolvers:

await createApp({
  name: 'my-app',
  modules: [userModule],
  resolvers: [new ApiResolver()],
  extend: async (scope) => {
    // Add any CDKTN construct directly to the stack
  },
});