Homepage

Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement Serverless best practices and increase developer velocity.

You can use Powertools for AWS Lambda in both TypeScript and JavaScript code bases.

• Features

  ---

  Adopt one, a few, or all industry practices. Progressively.

  All features

• Support this project

  ---

  Become a public reference customer, share your work, contribute, use Lambda Layers, etc.

  Support

• Available languages

  ---

  Powertools for AWS Lambda is also available in other languages

  Python, Java, and .NET

Install

You can use Powertools for AWS Lambda (TypeScript) by installing it with your favorite dependency management, or via Lambda Layers:

npmjs.comLambda Layer

All features are available as individual packages, so you can install only the ones you need, for example:

• Logger: npm i @aws-lambda-powertools/logger
• Metrics: npm i @aws-lambda-powertools/metrics
• Tracer: npm i @aws-lambda-powertools/tracer

Extra dependencies

Some features use additional dependencies like the AWS SDK for JavaScript v3, which might you need to install separately if you are using any of the features below:

Feature	Install	Default dependency
Tracer	npm i @aws-lambda-powertools/tracer	aws-xray-sdk-core
Idempotency	npm i @aws-lambda-powertools/idempotency @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
Parameters (SSM)	npm i @aws-lambda-powertools/parameters @aws-sdk/client-ssm
Parameters (Secrets Manager)	npm i @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager
Parameters (AppConfig)	npm i @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata
Parser	npm i @aws-lambda-powertools/parser zod@~3

You can add our layer both in the AWS Lambda Console (under Layers), or via your favorite infrastructure as code framework with the ARN value.

For the latter, make sure to replace {region} with your AWS region, e.g., eu-west-1.

arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17

Code snippets for popular infrastructure as code frameworks

CDKSAMServerless frameworkTerraformPulumiAmplify

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { LayerVersion, Function, Runtime, Code } from 'aws-cdk-lib/aws-lambda';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

export class SampleFunctionWithLayer extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // Create a Layer with Powertools for AWS Lambda (TypeScript)
    const powertoolsLayer = LayerVersion.fromLayerVersionArn(
      this,
      'PowertoolsLayer',
      `arn:aws:lambda:${Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17`
    );

    new Function(this, 'Function', {
      runtime: Runtime.NODEJS_22_X,
      // Add the Layer to a Lambda function
      layers: [powertoolsLayer],
      code: Code.fromInline(`...`),
      handler: 'index.handler',
    });
  }
}

If you use esbuild to bundle your code, make sure to exclude @aws-lambda-powertools/* and @aws-sdk/* from being bundled since the packages are already present the layer:

new NodejsFunction(this, 'Function', {
  ...
  bundling: {
    externalModules: [
      '@aws-lambda-powertools/*',
      '@aws-sdk/*',
    ],
  }
});

Check the documentation for more details.

MyLambdaFunction:
  Type: AWS::Serverless::Function
    Properties:
      Layers:
        - !Sub arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17

If you use esbuild to bundle your code, make sure to exclude @aws-lambda-powertools/* and @aws-sdk/* from being bundled since the packages are already present the layer:

MyLambdaFunction:
  Type: AWS::Serverless::Function
  Properties:
    ...
    Metadata: 
      # Manage esbuild properties
      BuildMethod: esbuild
      BuildProperties:
      Minify: true
      External:
        - '@aws-lambda-powertools/*'
        - '@aws-sdk/*'

Check the documentation for more details.

functions:
  hello:
    handler: lambda_function.lambda_handler
    layers:
      - arn:aws:lambda:${aws:region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17

If you use esbuild to bundle your code, make sure to exclude @aws-lambda-powertools/* and @aws-sdk/* from being bundled since the packages are already present the layer:

custom:
  esbuild:
    external:
      - '@aws-lambda-powertools/*'
      - '@aws-sdk/*'

Check the documentation for more details.

terraform {
  required_version = "~> 1.0.5"
  required_providers {
    aws = "~> 3.50.0"
  }
}

provider "aws" {
  region  = "{aws::region}"
}

resource "aws_lambda_function" "test_lambda" {
  filename      = "lambda_function_payload.zip"
  function_name = "lambda_function_name"
  role          = ...
  handler       = "index.handler"
  runtime       = "nodejs22.x"
  layers        = ["arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17"]
  source_code_hash = filebase64sha256("lambda_function_payload.zip")
}

import * as pulumi from '@pulumi/pulumi';
import * as aws from '@pulumi/aws';

const role = new aws.iam.Role('role', {
    assumeRolePolicy: aws.iam.assumeRolePolicyForPrincipal(aws.iam.Principals.LambdaPrincipal),
    managedPolicyArns: [aws.iam.ManagedPolicies.AWSLambdaBasicExecutionRole]
});

const lambdaFunction = new aws.lambda.Function('function', {
    layers: [
        pulumi.interpolate`arn:aws:lambda:${aws.getRegionOutput().name}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17`
    ],
    code: new pulumi.asset.FileArchive('lambda_function_payload.zip'),
    tracingConfig: {
        mode: 'Active'
    },
    runtime: aws.lambda.Runtime.NodeJS22dX,
    handler: 'index.handler',
    role: role.arn,
    architectures: ['x86_64']
});

Remember to replace the region with your AWS region, e.g., eu-west-1. Amplify Gen 2 currently does not support obtaining the region dynamically.

import { defineFunction } from "@aws-amplify/backend";

export const myFunction = defineFunction({
  name: "my-function",
  layers: {
    "@aws-lambda-powertools/*":
      "arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17",
  },
});

Lambda Layer

Lambda Layer is a .zip file archive that can contain additional code, pre-packaged dependencies, data, or configuration files. We compile and optimize all dependencies to achieve an optimal build.

You can use the Lambda Layer both with CommonJS and ESM (ECMAScript modules) for Node.js 18.x and newer runtimes.

Click to expand and copy any regional Lambda Layer ARN

Region	Layer ARN
us-east-1	arn:aws:lambda:us-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
us-east-2	arn:aws:lambda:us-east-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
us-west-1	arn:aws:lambda:us-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
us-west-2	arn:aws:lambda:us-west-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-south-1	arn:aws:lambda:ap-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-south-2	arn:aws:lambda:ap-south-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-east-1	arn:aws:lambda:ap-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-northeast-1	arn:aws:lambda:ap-northeast-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-northeast-2	arn:aws:lambda:ap-northeast-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-northeast-3	arn:aws:lambda:ap-northeast-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-southeast-1	arn:aws:lambda:ap-southeast-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-southeast-2	arn:aws:lambda:ap-southeast-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-southeast-3	arn:aws:lambda:ap-southeast-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ap-southeast-4	arn:aws:lambda:ap-southeast-4:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
eu-central-1	arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
eu-central-2	arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
eu-west-1	arn:aws:lambda:eu-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
eu-west-2	arn:aws:lambda:eu-west-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
eu-west-3	arn:aws:lambda:eu-west-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
eu-north-1	arn:aws:lambda:eu-north-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
eu-south-1	arn:aws:lambda:eu-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
eu-south-2	arn:aws:lambda:eu-south-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ca-central-1	arn:aws:lambda:ca-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
ca-west-1	arn:aws:lambda:ca-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
sa-east-1	arn:aws:lambda:sa-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
af-south-1	arn:aws:lambda:af-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
me-south-1	arn:aws:lambda:me-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
me-central-1	arn:aws:lambda:me-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17
il-central-1	arn:aws:lambda:il-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17

Want to inspect the contents of the Layer?

The pre-signed URL to download this Lambda Layer will be within Location key in the CLI output. The CLI output will also contain the Powertools for AWS Lambda version it contains.

Change {aws::region} to your AWS region, e.g. eu-west-1, and run the following command:

aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:17 --region {aws::region}

Instrumentation

Many of the utilities provided by Powertools for AWS Lambda (TypeScript) can be used with different programming paradigms:

• Middy middleware. It is the best choice if your existing code base relies on the Middy.js middleware engine. Powertools for AWS Lambda (TypeScript) offers compatible Middy middleware to make this integration seamless.
• Method decorator. Use TypeScript method decorators if you prefer writing your business logic using TypeScript Classes. If you aren’t using Classes, this requires the most significant refactoring.
• Manually. It provides the most granular control. It’s the most verbose approach, with the added benefit of no additional dependency and no refactoring to TypeScript Classes.

The examples in this documentation will feature all the approaches described above wherever applicable.

Examples

You can find examples of how to use Powertools for AWS Lambda (TypeScript) in the examples directory. The application is a simple REST API that can be deployed via either AWS CDK or AWS SAM.

If instead you want to see Powertools for AWS Lambda (TypeScript) in slightly different use cases, check the Serverless TypeScript Demo or the AWS Lambda performance tuning repository. Both demos use Powertools for AWS Lambda (TypeScript) as well as demonstrating other common techniques for Lambda functions written in TypeScript.

Features

Core utilities such as Tracing, Logging, and Metrics will be available across all Powertools for AWS Lambda languages. Additional utilities are subjective to each language ecosystem and customer demand.

Utility	Description
Tracer	Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
Logger	Structured logging made easier, and a middleware to enrich structured logging with key Lambda context details
Metrics	Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
Parameters	High-level functions to retrieve one or more parameters from AWS SSM Parameter Store, AWS Secrets Manager, AWS AppConfig, and Amazon DynamoDB
Idempotency	Class method decorator, Middy middleware, and function wrapper to make your Lambda functions idempotent and prevent duplicate execution based on payload content.
Batch Processing	Utility to handle partial failures when processing batches from Amazon SQS, Amazon Kinesis Data Streams, and Amazon DynamoDB Streams.
Parser	Utility to parse and validate AWS Lambda event payloads using Zod, a TypeScript-first schema declaration and validation library.

Environment variables

Info

Explicit parameters take precedence over environment variables

Environment variable	Description	Utility	Default
POWERTOOLS_SERVICE_NAME	Set service name used for tracing namespace, metrics dimension and structured logging	All	service_undefined
POWERTOOLS_METRICS_NAMESPACE	Set namespace used for metrics	Metrics	default_namespace
POWERTOOLS_METRICS_ENABLED	Explicitly disables emitting metrics to stdout	Metrics	true
POWERTOOLS_TRACE_ENABLED	Explicitly disables tracing	Tracer	true
POWERTOOLS_TRACER_CAPTURE_RESPONSE	Capture Lambda or method return as metadata.	Tracer	true
POWERTOOLS_TRACER_CAPTURE_ERROR	Capture Lambda or method exception as metadata.	Tracer	true
POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS	Capture HTTP(s) requests as segments.	Tracer	true
POWERTOOLS_LOGGER_LOG_EVENT	Log incoming event	Logger	false
POWERTOOLS_LOGGER_SAMPLE_RATE	Debug log sampling	Logger	0
POWERTOOLS_DEV	Increase JSON indentation to ease debugging when running functions locally or in a non-production environment	Logger	false
POWERTOOLS_LOG_LEVEL	Sets how verbose Logger should be, from the most verbose to the least verbose (no logs)	Logger	INFO
POWERTOOLS_PARAMETERS_MAX_AGE	Adjust how long values are kept in cache (in seconds)	Parameters	5
POWERTOOLS_PARAMETERS_SSM_DECRYPT	Set whether to decrypt or not values retrieved from AWS Systems Manager Parameters Store	Parameters	false
POWERTOOLS_IDEMPOTENCY_DISABLED	Disable the Idempotency logic without changing your code, useful for testing	Idempotency	false

Each Utility page provides information on example values and allowed values.

Optimizing for non-production environments

Whether you're prototyping locally or against a non-production environment, you can use POWERTOOLS_DEV to increase verbosity across multiple utilities.

When POWERTOOLS_DEV is set to a truthy value (1, true), it'll have the following effects:

Utility	Effect
Logger	Increase JSON indentation to 4 and uses global console to emit logs to ease testing and local debugging when running functions locally. However, Amazon CloudWatch Logs view will degrade as each new line is treated as a new message
Tracer	Disables tracing operations in non-Lambda environments. This already happens automatically in the Tracer utility
Metrics	Disables emitting metrics to stdout. Can be overridden by setting POWERTOOLS_METRICS_ENABLED to true

Support Powertools for AWS Lambda (TypeScript)

There are many ways you can help us gain future investments to improve everyone's experience:

• Become a public reference

  ---

  Add your company name and logo on our landing page, documentation, and README files.

  GitHub Issue template

• Share your work

  ---

  Blog posts, video, and sample projects about Powertools for AWS Lambda.

  GitHub Issue template

• Join the community

  ---

  Connect, ask questions, and share what features you use.

  Discord invite

Becoming a reference customer

Knowing which companies are using this library is important to help prioritize the project internally. The following companies, among others, use Powertools:

Alma Media

AppYourself

Bailey Nelson

Banxware

Caylent

Certible

Elva

Flyweight

globaldatanet

Hashnode

LocalStack

Perfect Post

Sennder

tecRacer GmbH & Co. KG

Trek10

WeSchool

Using Lambda Layers

Layers help us understand who uses Powertools for AWS Lambda (TypeScript) in a non-intrusive way.

When using Layers, you can add Powertools for AWS Lambda (TypeScript) as a dev dependency to not impact the development process. For Layers, we pre-package all dependencies, compile and optimize for storage.

Tenets

These are our core principles to guide our decision making.

• AWS Lambda only. We optimise for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported.
• Eases the adoption of best practices. The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional.
• Keep it lean. Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time.
• We strive for backwards compatibility. New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined.
• We work backwards from the community. We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs)
• Progressive. Utilities are designed to be incrementally adoptable for customers at any stage of their Serverless journey. They follow language idioms and their community’s common practices.