Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Building applications

To build your serverless application, use the sam build command. This command also gathers the build artifacts of your application's dependencies and places them in the proper format and location for next steps, such as locally testing, packaging, and deploying.

You specify your application's dependencies in a manifest file, such as requirements.txt (Python) or package.json (Node.js), or by using the Layers property of a function resource. The Layers property contains a list of Amazon Lambda layer resources that the Lambda function depends on.

The format of your application's build artifacts depends on each function's PackageType property. The options for this property are:

For more information about Lambda package types, see Lambda deployment packages in the Amazon Lambda Developer Guide.

Building a .zip file archive

To build your serverless application as a .zip file archive, declare PackageType: Zip for your serverless function.

Amazon SAM builds your application for the architecture that you specify. If you don't specify an architecture, Amazon SAM uses x86_64 by default.

If your Lambda function depends on packages that have natively compiled programs, use the --use-container flag. This flag locally compiles your functions in a Docker container that behaves like a Lambda environment, so they're in the right format when you deploy them to the Amazon Cloud.

When you use the --use-container option, by default Amazon SAM pulls the container image from Amazon ECR Public. If you would like to pull a container image from another repository, for example DockerHub, you can use the --build-image option and provide the URI of an alternate container image. Following are two example commands for building applications using container images from the DockerHub repository:

# Build a Node.js 20 application using a container image pulled from DockerHub
sam build --use-container --build-image amazon/aws-sam-cli-build-image-nodejs20.x

# Build a function resource using the Python 3.12 container image pulled from DockerHub
sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.12 

For a list of URIs you can use with --build-image, see Image repositories which contains DockerHub URIs for a number of supported runtimes.

For additional examples of building a .zip file archive application, see the Examples section later in this topic.

Building a container image

To build your serverless application as a container image, declare PackageType: Image for your serverless function. You must also declare the Metadata resource attribute with the following entries:

The following is an example Metadata resource attribute section:

    Metadata:
      Dockerfile: Dockerfile
      DockerContext: ./hello_world
      DockerTag: v1

To download a sample application that's configured with the Image package type, see Tutorial: Deploying a Hello World application in Tutorial: Deploying a Hello World application. At the prompt asking which package type you want to install, choose Image.

Container environment variable file

To provide a JSON file that contains environment variables for the build container, use the --container-env-var-file argument with the sam build command. You can provide a single environment variable that applies to all serverless resources, or different environment variables for each resource.

Format

The format for passing environment variables to a build container depends on how many environment variables you provide for your resources.

To provide a single environment variable for all resources, specify a Parameters object like the following:

{
  "Parameters": {
    "GITHUB_TOKEN": "TOKEN_GLOBAL"
  }
}

To provide different environment variables for each resource, specify objects for each resource like the following:

{
  "MyFunction1": {
    "GITHUB_TOKEN": "TOKEN1"
  },
  "MyFunction2": {
    "GITHUB_TOKEN": "TOKEN2"
  }
}

Save your environment variables as a file, for example, named env.json. The following command uses this file to pass your environment variables to the build container:

sam build --use-container --container-env-var-file env.json

Precedence

Speed up build times by building your project in the source folder

For supported runtimes and build methods, you can use the --build-in-source option to build your project directly in the source folder. By default, the Amazon SAM CLI builds in a temporary directory, which involves copying over source code and project files. With --build-in-source, the Amazon SAM CLI builds directly in your source folder, which speeds up the build process by removing the need to copy files to a temporary directory.

For a list of supported runtimes and build methods, see --build-in-source.

Examples

Example 1: .zip file archive

The following sam build commands build a .zip file archive:

# Build all functions and layers, and their dependencies
sam build

# Run the build process inside a Docker container that functions like a Lambda environment
sam build --use-container

# Build a Node.js 20 application using a container image pulled from DockerHub
sam build --use-container --build-image amazon/aws-sam-cli-build-image-nodejs20.x

# Build a function resource using the Python 3.12 container image pulled from DockerHub
sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.12 

# Build and run your functions locally
sam build && sam local invoke

# For more options
sam build --help

Example 2: Container image

The following Amazon SAM template builds as a container image:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      PackageType: Image
      ImageConfig:
        Command: ["app.lambda_handler"]
    Metadata:
      Dockerfile: Dockerfile
      DockerContext: ./hello_world
      DockerTag: v1

The following is an example Dockerfile:

FROM public.ecr.aws/lambda/python:3.12

COPY app.py requirements.txt ./

RUN python3.12 -m pip install -r requirements.txt

# Overwrite the command by providing a different command directly in the template.
CMD ["app.lambda_handler"]

Example 3: npm ci

For Node.js applications, you can use npm ci instead of npm install to install dependencies. To use npm ci, specify UseNpmCi: True under BuildProperties in your Lambda function's Metadata resource attribute. To use npm ci, your application must have a package-lock.json or npm-shrinkwrap.json file present in the CodeUri for your Lambda function.

The following example uses npm ci to install dependencies when you run sam build:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: hello-world/
      Handler: app.handler
      Runtime: nodejs20.x
      Architectures:
        - x86_64
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /hello
            Method: get
    Metadata:
      BuildProperties:
        UseNpmCi: True

Building functions outside of Amazon SAM

By default, when you run sam build, Amazon SAM builds all of your function resources. Other options include:

Build some function resources outside of Amazon SAM

To have Amazon SAM skip a function when using sam build, configure the following in your Amazon SAM template:

Here is an example, with TestFunction configured to be skipped. Its built resources are located at built-resources/TestFunction.zip.

TestFunction:
  Type: AWS::Serverless::Function
  Properties:
    CodeUri: built-resources/TestFunction.zip
    Handler: TimeHandler::handleRequest
    Runtime: java11
  Metadata:
    SkipBuild: True

Now, when you run sam build, Amazon SAM will do the following: