skills/aws-lambda-typescript-integration/references/serverless-config.md

Serverless Configuration Reference

Complete reference for deploying NestJS Lambda applications using Serverless Framework and AWS SAM.

Serverless Framework

Basic Configuration

service: nestjs-lambda-api

provider:
  name: aws
  runtime: nodejs20.x
  region: ${opt:region, 'us-east-1'}
  stage: ${opt:stage, 'dev'}
  memorySize: 512
  timeout: 29
  environment:
    NODE_ENV: production
    DATABASE_URL: ${ssm:/${self:service}/${self:provider.stage}/database-url}
    JWT_SECRET: ${ssm:/${self:service}/${self:provider.stage}/jwt-secret}
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - logs:CreateLogGroup
            - logs:CreateLogStream
            - logs:PutLogEvents
          Resource:
            - !Sub 'arn:aws:logs:${aws:region}:${aws:accountId}:log-group:/aws/lambda/${self:service}-*'

package:
  individually: false
  patterns:
    - '!node_modules/**'
    - '!test/**'
    - '!.git/**'
    - 'dist/**'
    - '!dist/tsconfig.build.tsbuildinfo'

custom:
  esbuild:
    bundle: true
    minify: true
    target: node20
    platform: node
    external:
      - '@nestjs/microservices'
      - '@nestjs/websockets'
      - 'class-transformer/storage'

functions:
  api:
    handler: dist/lambda.handler
    events:
      - http:
          path: /{proxy+}
          method: ANY
          cors: true
      - http:
          path: /
          method: ANY
          cors: true
    provisionedConcurrency: ${self:custom.provisionedConcurrency.${self:provider.stage}, 0}

custom:
  provisionedConcurrency:
    prod: 5
    dev: 0

plugins:
  - serverless-esbuild
  - serverless-offline

Commands

# Deploy
serverless deploy
serverless deploy --stage prod --region eu-west-1

# Local development
serverless offline

# Logs
serverless logs -f api -t

# Remove
serverless remove

AWS SAM

Basic Template

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: NestJS Lambda API

Globals:
  Function:
    Timeout: 29
    MemorySize: 512
    Runtime: nodejs20.x
    Architectures:
      - x86_64

Parameters:
  Environment:
    Type: String
    Default: dev
    AllowedValues:
      - dev
      - staging
      - prod

Resources:
  NestJSApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: !Sub '${AWS::StackName}-api'
      Handler: dist/lambda.handler
      CodeUri: ./
      Environment:
        Variables:
          NODE_ENV: !Ref Environment
          DATABASE_URL: !Sub '{{resolve:ssm-secure:/${AWS::StackName}/database-url}}'
      Events:
        ApiGatewayRoot:
          Type: Api
          Properties:
            Path: /
            Method: ANY
            RestApiId: !Ref ApiGatewayApi
        ApiGatewayProxy:
          Type: Api
          Properties:
            Path: /{proxy+}
            Method: ANY
            RestApiId: !Ref ApiGatewayApi
      Policies:
        - AWSLambdaBasicExecutionRole

  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: !Ref Environment
      Cors:
        AllowMethods: "'GET,POST,PUT,DELETE,OPTIONS'"
        AllowHeaders: "'Content-Type,Authorization'"
        AllowOrigin: !Sub "'${AllowedOrigins}'"

Outputs:
  ApiUrl:
    Description: API Gateway endpoint URL
    Value: !Sub 'https://${ApiGatewayApi}.execute-api.${AWS::Region}.amazonaws.com/${Environment}/'

Commands

# Build
sam build

# Local development
sam local start-api --warm-containers EAGER

# Deploy
sam deploy --guided
sam deploy --config-env prod

# Logs
sam logs -n NestJSApiFunction --tail

# Delete
sam delete

Comparison

Feature	SAM	Serverless Framework
Native AWS	Yes	No (uses CloudFormation)
Local testing	sam local	serverless-offline
CI/CD integration	AWS-native	Multi-cloud support
Syntax	YAML/JSON	YAML/TypeScript/JavaScript
Plugins	SAR, nested stacks	Rich plugin ecosystem

When to Choose

Choose SAM when:

• Native AWS environment
• Team familiar with CloudFormation
• Deep AWS service integration needed
• AWS CodePipeline/CodeBuild usage

Choose Serverless Framework when:

• Multi-cloud requirements
• Large plugin ecosystem needed
• Prefer TypeScript/JavaScript config
• Easier local development preferred