Fjall Docs — deploy AWS infrastructure into your own account

Overview

The Lambda Function resource provides serverless compute with automatic scaling, built-in high availability, and pay-per-use pricing. It covers both standard functions and singleton functions for AWS Custom Resources.

Resource Classes

import {
  LambdaFunction,
  SingletonFunction,
} from "@fjall/components-infrastructure/lib/resources/aws/compute/lambda";

The deep lib/... path is a published subpath of the package. The Lambda and ECS constructs are not re-exported from the package root (the EC2 construct is), so this import is the only one that compiles for LambdaFunction.

This page covers using the construct class directly. The scaffolded fjall/<app>/infrastructure.ts that fjall create app writes never does that: it imports App and the *Factory symbols from the package root, and fjall add edits it through the codemod engine.

Basic Usage

Standard Function

const lambda = new LambdaFunction(this, "MyFunction", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [
    new PolicyStatement({
      actions: ["s3:GetObject"],
      resources: ["arn:aws:s3:::my-bucket/*"],
    }),
  ],
});

Singleton Function

const singleton = new SingletonFunction(this, "CustomResource", {
  code: Code.fromInline("exports.handler = async () => ({ statusCode: 200 })"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [],
});

uuid is optional. Omit it and the construct derives a stable one from the construct path. See Singleton Function Pattern.

Configuration Options

Core Properties

Property	Type	Description	Default
`code`	`Code`	Function code source	Required
`handler`	`string`	Handler function	Required
`runtime`	`Runtime`	Lambda runtime	Required
`inlinePolicy`	`PolicyStatement[]`	IAM policy statements	Required

Function Configuration

Property	Type	Description	Default
`timeout`	`number`	Timeout in seconds	`300`
`memorySize`	`number`	Memory in MB (128-10240)	`128`
`reservedConcurrentExecutions`	`number`	Cap on concurrent executions	Unset
`ephemeralStorageSize`	`number`	Ephemeral storage in MiB	-
`architecture`	`Architecture`	CPU architecture	`x86_64`
`lambdaDescription`	`string`	Function description	`${id} Lambda`
`environment`	`KeyValue`	Environment variables	`{}`
`functionName`	`string`	Explicit function name	Auto-generated
`vpc`	`IVpc`	Place the function in a VPC	-
`logGroupRetention`	`RetentionDays`	Log retention for the auto-created log group	`ONE_WEEK`

SingletonFunction defaults lambdaDescription to ${id} singleton lambda instead. Passing vpc also picks the subnet type: PRIVATE_WITH_EGRESS when the VPC has NAT gateways, otherwise PRIVATE_ISOLATED.

Execution Role

Property	Type	Description	Default
`roleDescription`	`string`	Description written onto the auto-generated role	-
`rolePath`	`string`	Fixed IAM path for the role, for example `/fjall/`	-
`roleName`	`string`	Fixed role name	-

Set rolePath and roleName together when an SCP exemption needs to match a predictable role ARN.

A fixed roleName is account-global. Only set one on a Lambda confined to a single account and region stack, or regional duplicates collide on the role name at deploy time.

Function URL Properties

Property	Type	Description	Default
`enableFunctionUrl`	`boolean`	Enable HTTP endpoint	`false`
`functionUrlAuthType`	`FunctionUrlAuthType`	Auth type	`AWS_IAM`
`functionUrlCors`	`FunctionUrlCorsOptions`	CORS configuration	-
`functionUrlInvokeMode`	`InvokeMode`	Invoke mode (use RESPONSE_STREAM for streaming)	-

Async Failure Handling

Property	Type	Description	Default
`asyncFailureQueue`	`IQueue \| false`	Dead-letter queue for async invocations	Auto-created queue

See Async failure queue for when the queue is created.

Secrets Configuration

Property	Type	Description	Default
`secrets`	`string[]`	SSM Parameter Store secret names	-
`ssmSecretsPath`	`string`	Base path for SSM secrets	`/<appName>/lambda/<functionName>`
`secretsImport`	`Record<string, SecretImport>`	Secrets Manager imports	-
`appName`	`string`	Application name for the SSM namespace	-

The ssmSecretsPath default only resolves when both appName and functionName are supplied. With secrets set and neither an explicit path nor both names available, the construct throws at synth.

Alarms

Property	Type	Description	Default
`alertsTopic`	`ITopic`	SNS topic for alarm notifications	-
`alarms`	`LambdaAlarmThresholds \| false`	Thresholds, or `false` to disable	Defaults when a topic is set
`applicationId`	`string`	Application ID for alarm tagging	-

Alarms are only created when alertsTopic is set and alarms is not false. LambdaAlarmThresholds accepts errorRateThreshold and durationThresholdPercent.

Runtimes

Both constructs reject deprecated runtimes at synth, before any deploy, and fail with:

Lambda 'MyFunction': runtime 'nodejs18.x' is deprecated by AWS Lambda. Migrate to a supported runtime — e.g. Runtime.NODEJS_24_X for Node.js.

Rejected runtime names:

Family	Rejected
Node.js	`nodejs`, `nodejs4.3`, `nodejs6.10`, `nodejs8.10`, `nodejs10.x`, `nodejs12.x`, `nodejs14.x`, `nodejs16.x`, `nodejs18.x`
Python	`python2.7`, `python3.6`, `python3.7`, `python3.8`, `python3.9`
Java	`java8`
.NET	`dotnet6`, `dotnetcore1.0`, `dotnetcore2.0`, `dotnetcore2.1`, `dotnetcore3.1`
Go	`go1.x`
Ruby	`ruby2.5`, `ruby2.7`
Custom	`provided`

This guard shifts the posture scan’s LAMBDA_DEPRECATED_RUNTIME finding left. Without it the deploy succeeds and the finding surfaces days later. A deprecated runtime receives no security patches, and AWS eventually blocks function creation on it.

Code Sources

From Local Directory

const lambda = new LambdaFunction(this, "LocalCode", {
  code: Code.fromAsset("src/lambda"),
  handler: "app.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [],
});

From Inline Code

const lambda = new LambdaFunction(this, "InlineCode", {
  code: Code.fromInline(`
    exports.handler = async (event) => {
      console.log("Event:", JSON.stringify(event));
      return {
        statusCode: 200,
        body: JSON.stringify({ message: "Hello World" })
      };
    };
  `),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [],
});

From S3 Bucket

const lambda = new LambdaFunction(this, "S3Code", {
  code: Code.fromBucket(
    s3.Bucket.fromBucketName(this, "CodeBucket", "my-code-bucket"),
    "lambda-code.zip",
  ),
  handler: "main.handler",
  runtime: Runtime.PYTHON_3_13,
  inlinePolicy: [],
});

From Docker Image

const lambda = new LambdaFunction(this, "ContainerFunction", {
  code: Code.fromEcrImage(repository, {
    tagOrDigest: "latest",
  }),
  handler: Handler.FROM_IMAGE,
  runtime: Runtime.FROM_IMAGE,
  inlinePolicy: [],
});

IAM Policies

The inlinePolicy property accepts an array of PolicyStatement objects. Each statement is added directly to the Lambda function’s execution role.

S3 Access

const lambda = new LambdaFunction(this, "S3Function", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [
    new PolicyStatement({
      actions: ["s3:GetObject", "s3:PutObject"],
      resources: [`${bucket.bucketArn}/*`],
    }),
  ],
});

DynamoDB Access

const lambda = new LambdaFunction(this, "DynamoFunction", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [
    new PolicyStatement({
      actions: [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:Query",
        "dynamodb:Scan",
      ],
      resources: [table.tableArn],
    }),
  ],
});

Multiple Policy Statements

const lambda = new LambdaFunction(this, "MultiPolicyFunction", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [
    new PolicyStatement({
      actions: ["s3:GetObject"],
      resources: [`${bucket.bucketArn}/*`],
    }),
    new PolicyStatement({
      actions: ["dynamodb:Query"],
      resources: [table.tableArn],
    }),
    new PolicyStatement({
      actions: ["sqs:SendMessage"],
      resources: [queue.queueArn],
    }),
  ],
});

Environment Variables

const lambda = new LambdaFunction(this, "EnvFunction", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  environment: {
    TABLE_NAME: dynamoTable.tableName,
    BUCKET_NAME: s3Bucket.bucketName,
    STAGE: "production",
  },
  inlinePolicy: [],
});

Function URL Configuration

Basic HTTP Endpoint

FunctionUrlAuthType.NONE publishes an unauthenticated endpoint. Cap it with reservedConcurrentExecutions, which bounds both the function’s own spend and the share of account-wide concurrency an anonymous caller can take from every other function in the account.

const lambda = new LambdaFunction(this, "HttpFunction", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  enableFunctionUrl: true,
  functionUrlAuthType: FunctionUrlAuthType.NONE,
  reservedConcurrentExecutions: 20,
  inlinePolicy: [],
});

Omitting reservedConcurrentExecutions on a NONE Function URL raises a synth-time CDK warning: “exposes a public Function URL (authType NONE) without reservedConcurrentExecutions”. The synth still succeeds, so the warning is easy to miss in CI output.

With CORS

const lambda = new LambdaFunction(this, "CorsFunction", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  enableFunctionUrl: true,
  functionUrlAuthType: FunctionUrlAuthType.AWS_IAM,
  functionUrlCors: {
    allowedOrigins: ["https://example.com"],
    allowedMethods: [HttpMethod.GET, HttpMethod.POST],
    allowedHeaders: ["Content-Type", "Authorization"],
    maxAge: Duration.hours(1),
  },
  inlinePolicy: [],
});

Performance Configuration

High Memory Function

const mlFunction = new LambdaFunction(this, "MLFunction", {
  code: Code.fromAsset("lambda"),
  handler: "predict.handler",
  runtime: Runtime.PYTHON_3_13,
  memorySize: 10240, // Maximum: 10240 MB
  timeout: 900, // 15 minutes
  inlinePolicy: [
    new PolicyStatement({
      actions: ["s3:GetObject"],
      resources: ["arn:aws:s3:::ml-models/*"],
    }),
  ],
});

ARM Architecture

const lambda = new LambdaFunction(this, "ArmFunction", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  architecture: Architecture.ARM_64,
  inlinePolicy: [],
});

Event Sources

LambdaFunction provides three built-in event-source methods: addSqsEventSource, addDynamoDbEventSource, and addS3EventSource.

SQS Trigger

const processor = new LambdaFunction(this, "QueueProcessor", {
  code: Code.fromAsset("lambda"),
  handler: "queue.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [
    new PolicyStatement({
      actions: ["sqs:ReceiveMessage", "sqs:DeleteMessage"],
      resources: [queue.queueArn],
    }),
  ],
});

processor.addSqsEventSource(queue, {
  batchSize: 10,
  maxBatchingWindow: 30,
  reportBatchItemFailures: true,
});

Defaults: batchSize 10, reportBatchItemFailures true. maxBatchingWindow is in seconds.

DynamoDB Stream Trigger

const streamProcessor = new LambdaFunction(this, "StreamProcessor", {
  code: Code.fromAsset("lambda"),
  handler: "stream.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [
    new PolicyStatement({
      actions: [
        "dynamodb:GetRecords",
        "dynamodb:GetShardIterator",
        "dynamodb:DescribeStream",
        "dynamodb:ListStreams",
      ],
      resources: [`${table.tableArn}/stream/*`],
    }),
  ],
});

streamProcessor.addDynamoDbEventSource(table, {
  startingPosition: "LATEST",
  batchSize: 100,
  reportBatchItemFailures: true,
});

Defaults: startingPosition "LATEST", batchSize 100, reportBatchItemFailures true. retryAttempts and parallelizationFactor are also accepted.

S3 Trigger

const fileProcessor = new LambdaFunction(this, "FileProcessor", {
  code: Code.fromAsset("lambda"),
  handler: "processor.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [
    new PolicyStatement({
      actions: ["s3:GetObject"],
      resources: [`${bucket.bucketArn}/*`],
    }),
  ],
});

fileProcessor.addS3EventSource(bucket, {
  events: ["OBJECT_CREATED"],
  filters: [{ prefix: "uploads/", suffix: ".csv" }],
});

Accepted events values: OBJECT_CREATED, OBJECT_REMOVED, OBJECT_CREATED_PUT, OBJECT_CREATED_POST, OBJECT_CREATED_COPY, OBJECT_REMOVED_DELETE. Defaults to ["OBJECT_CREATED"].

Async failure queue

S3 event notifications invoke the function asynchronously, and a failed event is dropped silently after the default two retries. To stop that, the first addS3EventSource call also creates an SQS queue and wires it as the function’s dead-letter destination.

Behaviour	Detail
Created	On the first `addS3EventSource` call, once per function
Queue settings	SSL enforced, SQS-managed encryption, 14-day retention
Wiring	`DeadLetterConfig` on the function plus an `sqs:SendMessage` grant to the execution role
Functions with no async source	No queue is created

Reuse an existing queue or opt out entirely:

// Reuse a queue you already own
const processor = new LambdaFunction(this, "FileProcessor", {
  code: Code.fromAsset("lambda"),
  handler: "processor.handler",
  runtime: Runtime.NODEJS_24_X,
  asyncFailureQueue: sharedFailureQueue,
  inlinePolicy: [],
});

// Opt out: failed async events are dropped after two retries
const fireAndForget = new LambdaFunction(this, "Notifier", {
  code: Code.fromAsset("lambda"),
  handler: "notify.handler",
  runtime: Runtime.NODEJS_24_X,
  asyncFailureQueue: false,
  inlinePolicy: [],
});

Read the wired queue back with processor.getAsyncFailureQueue().

Scheduling

The construct has no built-in scheduling method or prop. To run a function on a schedule, attach a standalone EventBridge Rule that targets the function.

import { Rule, Schedule } from "aws-cdk-lib/aws-events";
import { LambdaFunction as LambdaTarget } from "aws-cdk-lib/aws-events-targets";

const cleanup = new LambdaFunction(this, "DailyCleanup", {
  code: Code.fromAsset("lambda"),
  handler: "cron.handler",
  runtime: Runtime.NODEJS_24_X,
  inlinePolicy: [],
});

new Rule(this, "DailyCleanupSchedule", {
  schedule: Schedule.rate(Duration.days(1)),
  targets: [new LambdaTarget(cleanup)],
  description: "Daily cleanup job",
});

Singleton Function Pattern

uuid is optional. When omitted, the construct derives one from a sha256 of the construct path (scope.node.path plus id), so the logical ID SingletonLambda<uuid> stays stable across synths. A random default would recreate the singleton, and re-run any custom resource fronted by it, on every deploy.

Changing a supplied uuid changes the logical ID. CloudFormation replaces the singleton and re-runs any custom resource behind it. Pick a value once and leave it, or omit uuid and let the construct derive it.

Custom Resource Handler

const customResourceHandler = new SingletonFunction(
  this,
  "CustomResourceHandler",
  {
    uuid: "f7d4f730-4ee1-11e8-9c2d-fa7ae01bbebc",
    code: Code.fromInline(`
    const response = require("cfn-response");
    exports.handler = async (event, context) => {
      try {
        if (event.RequestType === "Delete") {
          // Cleanup logic
        } else {
          // Create/Update logic
        }
        await response.send(event, context, response.SUCCESS);
      } catch (error) {
        await response.send(event, context, response.FAILED);
      }
    };
  `),
    handler: "index.handler",
    runtime: Runtime.NODEJS_24_X,
    lambdaDescription: "Custom resource handler",
    inlinePolicy: [
      new PolicyStatement({
        actions: ["s3:ListAllMyBuckets"],
        resources: ["*"],
      }),
    ],
  },
);

SingletonFunction supports the core props, timeout, ephemeralStorageSize, logGroupRetention, lambdaDescription, and the execution-role props. Function URLs, event sources, secrets, and alarms are LambdaFunction only.

Methods

Get Function URL

const url = lambda.getFunctionUrl();
// Returns: string | undefined (only when enableFunctionUrl is true)

Get Async Failure Queue

const dlq = lambda.getAsyncFailureQueue();
// Returns: IQueue | undefined (undefined until an async event source is added)

Get Execution Role

const role = lambda.executionRole;
// Returns: IRole | undefined

Get Function ARN

const functionArn = lambda.functionArn;

Get Function Name

const functionName = lambda.functionName;

Outputs

LambdaFunction creates these CloudFormation outputs, keyed on the PascalCased construct ID:

<PascalCaseId>FunctionArn - Function ARN
<PascalCaseId>FunctionUrl - Function URL (only when enableFunctionUrl is true)

Complete Example

import { LambdaFunction } from "@fjall/components-infrastructure/lib/resources/aws/compute/lambda";
import { Code, Runtime } from "aws-cdk-lib/aws-lambda";
import { PolicyStatement } from "aws-cdk-lib/aws-iam";
import { FunctionUrlAuthType, HttpMethod } from "aws-cdk-lib/aws-lambda";

const userApi = new LambdaFunction(this, "UserAPIFunction", {
  code: Code.fromAsset("src/lambda/user-api"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  memorySize: 256,
  timeout: 30,
  environment: {
    TABLE_NAME: userTable.tableName,
    REGION: this.region,
  },
  enableFunctionUrl: true,
  functionUrlAuthType: FunctionUrlAuthType.AWS_IAM,
  functionUrlCors: {
    allowedOrigins: ["https://app.example.com"],
    allowedMethods: [
      HttpMethod.GET,
      HttpMethod.POST,
      HttpMethod.PUT,
      HttpMethod.DELETE,
    ],
    allowedHeaders: ["Content-Type", "Authorization"],
  },
  inlinePolicy: [
    new PolicyStatement({
      actions: [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:UpdateItem",
        "dynamodb:DeleteItem",
        "dynamodb:Query",
      ],
      resources: [userTable.tableArn],
    }),
  ],
});

Tagging

The construct takes no tags prop. Apply tags through the CDK Tags aspect after construction.

import { Tags } from "aws-cdk-lib";

Tags.of(userApi).add("Environment", "production");
Tags.of(userApi).add("Application", "user-service");

Best Practices

Keep functions small and focused on single tasks
Set appropriate timeouts rather than defaulting to the maximum
Cap public endpoints with reservedConcurrentExecutions
Keep the async failure queue on any function fed by S3 events
Use PolicyStatement arrays for least-privilege IAM
Consider ARM (Graviton2) for cost savings
Use secrets and secretsImport for sensitive values rather than plain environment variables

Performance Tips

Minimise package size to reduce cold starts
Reuse connections outside the handler function
Use provisioned concurrency for predictable traffic
Choose appropriate memory (CPU scales with memory)
Maximum memory is 10240 MB (10 GB)

Next Steps

Compute Factory

Provision compute through the higher-level factory pattern.

IAM Role

Scope execution permissions for your function.

SQS Queue

Configure the queues behind event sources and dead-letter destinations.

Secrets Manager

Inject secrets into your function at runtime.

​Overview

​Resource Classes

​Basic Usage

​Standard Function

​Singleton Function

​Configuration Options

​Core Properties

​Function Configuration

​Execution Role

​Function URL Properties

​Async Failure Handling

​Secrets Configuration

​Alarms

​Runtimes

​Code Sources

​From Local Directory

​From Inline Code

​From S3 Bucket

​From Docker Image

​IAM Policies

​S3 Access

​DynamoDB Access

​Multiple Policy Statements

​Environment Variables

​Function URL Configuration

​Basic HTTP Endpoint

​With CORS

​Performance Configuration

​High Memory Function

​ARM Architecture

​Event Sources

​SQS Trigger

​DynamoDB Stream Trigger

​S3 Trigger

​Async failure queue

​Scheduling

​Singleton Function Pattern

​Custom Resource Handler

​Methods

​Get Function URL

​Get Async Failure Queue

​Get Execution Role

​Get Function ARN

​Get Function Name

​Outputs

​Complete Example

​Tagging

​Best Practices

​Performance Tips

​Next Steps

Compute Factory

IAM Role

SQS Queue

Secrets Manager

Overview

Resource Classes

Basic Usage

Standard Function

Singleton Function

Configuration Options

Core Properties

Function Configuration

Execution Role

Function URL Properties

Async Failure Handling

Secrets Configuration

Alarms

Runtimes

Code Sources

From Local Directory

From Inline Code

From S3 Bucket

From Docker Image

IAM Policies

S3 Access

DynamoDB Access

Multiple Policy Statements

Environment Variables

Function URL Configuration

Basic HTTP Endpoint

With CORS

Performance Configuration

High Memory Function

ARM Architecture

Event Sources

SQS Trigger

DynamoDB Stream Trigger

S3 Trigger

Async failure queue

Scheduling

Singleton Function Pattern

Custom Resource Handler

Methods

Get Function URL

Get Async Failure Queue

Get Execution Role

Get Function ARN

Get Function Name

Outputs

Complete Example

Tagging

Best Practices

Performance Tips

Next Steps