Packaging



This document describes how Stacktape packages your code for deployment.

Packaging Lambda functions

stacktape-lambda-buildpack

The stacktape-lambda-buildpack is a built-in, zero-config, and highly optimized buildpack that creates a Lambda artifact from an entry file path.

  • Supported languages: Javascript, Typescript, Python, Java, and Go.
  • Caching: Your deployment packages are cached. Stacktape creates a checksum from all the necessary files (including package manager lockfiles). If a workload with the same checksum has already been deployed, the packaging and deployment are skipped.
  • Upload: Lambda function packages are zipped and uploaded to a pre-created S3 bucket. The upload uses S3 Transfer Acceleration, which sends the package to the nearest AWS edge location and then routes it to the bucket over the Amazon backbone network. This is faster and more secure but incurs additional transfer costs ($0.04 per GB). To disable this, set deploymentConfiguration.useS3TransferAcceleration to false in your stacktape.yml file.
resources:
  myLambda:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my-lambda.ts
      timeout: 10
      memory: 2048
Javascript and Typescript
  • Your source code and all its external dependencies are bundled into a single file. This ensures that you only ship the minimum required code. Stacktape uses esbuild for this process.
  • Source maps are automatically generated and included in your deployment package. The generated code also includes the source-map-support library to make them usable.
  • If a dependency uses a dynamic require() and cannot be statically built, it will be copied as-is instead.
  • If a dependency has a binary dependency, it will be installed in a Docker container (based on the runtime used) and copied to the deployment package. This ensures that your binary dependencies are usable even when deploying from a different operating system (such as Windows or macOS).
Python
  • Your source code and all its dependencies are packaged into a zip archive using Docker, so you do not need to have Python installed for deployment.
  • Supported versions: 3.7, 3.8, and 3.9 (default).
  • Package managers: pip, pipenv, and poetry are supported.
  • If your dependencies are defined in a non-standard file, you can specify its location using languageSpecificProperties.packageManagerFile and languageSpecificProperties.packageManager.
Java
  • Your source code and all its dependencies are packaged into a zip archive using Docker, so you do not need to have Java installed for deployment.
  • Supported versions: 8 and 11 (default).
  • Build tools: Gradle (default) and Maven are supported.
  • If your project uses Maven, set languageSpecificProperties.useMaven to true. Stacktape will convert your Maven project to a Gradle project and build it with Gradle, which is 2-10 times faster than Maven.
Go
  • Your source code and all its dependencies are packaged into a zip archive using Docker, so you do not need to have Go installed for deployment.
StpBuildpackLambdaPackagingAPI reference
entryfilePathRequired

Path to your app's entry point, relative to the Stacktape config file.

Type: string

For JS/TS: code is bundled into a single file. Dependencies with native binaries are installed separately. For Python: use module/file.py:app format when using runAppAs (WSGI/ASGI).

handlerFunction

The name of the handler function to be executed when the Lambda is invoked.

Type: string

includeFiles

A glob pattern of files to explicitly include in the deployment package.

Type: Array of string

The path is relative to your Stacktape configuration file.

excludeFiles

A glob pattern of files to explicitly exclude from the deployment package.

Type: Array of string

excludeDependencies

A list of dependencies to exclude from the deployment package.

Type: Array of string

languageSpecificConfig

Language-specific packaging configuration.

Type: EsLanguageSpecificConfig or PyLanguageSpecificConfig or JavaLanguageSpecificConfig or PhpLanguageSpecificConfig or DotnetLanguageSpecificConfig or GoLanguageSpecificConfig or RubyLanguageSpecificConfig

custom-artifact

With custom-artifact, you provide a path to your own pre-built artifact. If the specified path is a directory or an unzipped file, Stacktape will zip it. The zipped package is then uploaded to a pre-created S3 bucket using S3 Transfer Acceleration.

CustomArtifactLambdaPackagingAPI reference
packagePathRequired

The path to a pre-built deployment package.

Type: string

If the path points to a directory or a non-zip file, Stacktape will automatically zip it for you.

handler

The handler function to be executed when the Lambda is invoked.

Type: string

The syntax is {{filepath}}:{{functionName}}.

Example: my-lambda/index.js:default

Packaging containers

This section applies to web services, private services, worker services, multi-container workloads, and batch jobs.

stacktape-image-buildpack

The stacktape-image-buildpack is a built-in, zero-config, and highly optimized buildpack that creates a runnable container image from your source code.

  • Supported languages: Javascript, Typescript, Python, Java, and Go.
  • The image is uploaded to a pre-created ECR repository.
Javascript and Typescript
  • Your source code and all its external dependencies are bundled into a single file. This ensures that you only ship the minimum required code. Stacktape uses esbuild for this process.
  • Source maps are automatically generated and included in your deployment package. The generated code also includes the source-map-support library to make them usable.
  • If a dependency uses a dynamic require() and cannot be statically built, it will be copied as-is instead.
  • If a dependency has a binary dependency, it will be installed in a Docker container using a Docker multi-stage build.
  • The base image used is the latest LTS version of Node.js (node:18-alpine if your app does not require glibc-based binaries, or node:18 if it does).
Python
  • Your source code and all its dependencies are copied to a Docker container.
  • Supported versions: 3.7, 3.8, and 3.9 (default).
  • Package managers: pip, pipenv, and poetry are supported.
  • If your dependencies are defined in a non-standard file, you can specify its location using languageSpecificProperties.packageManagerFile and languageSpecificProperties.packageManager.
  • Base image: public.ecr.aws/docker/library/python:${pythonVersion}-alpine (if your app does not require glibc-based binaries) or public.ecr.aws/docker/library/python:${pythonVersion} (if it does).
Java
  • Your source code and all its dependencies are copied to a Docker container.
  • Supported versions: 8 and 11 (default).
  • Build tools: Gradle (default) and Maven are supported.
  • If your project uses Maven, set languageSpecificProperties.useMaven to true. Stacktape will convert your Maven project to a Gradle project and build it with Gradle, which is 2-10 times faster than Maven.
  • Base image: public.ecr.aws/docker/library/gradle:7.5.1-jdk${javaVersion}-alpine (if your app does not require glibc-based binaries) or public.ecr.aws/docker/library/gradle:7.5.1-jdk${javaVersion} (if it does).
Go
  • Your source code and all its dependencies are copied to a Docker container.
  • Base image: public.ecr.aws/docker/library/golang-alpine (if your app does not require glibc-based binaries) or public.ecr.aws/docker/library/golang (if it does).
StpBuildpackCwImagePackagingAPI reference
entryfilePathRequired

Path to your app's entry point, relative to the Stacktape config file.

Type: string

For JS/TS: code is bundled into a single file. Dependencies with native binaries are installed separately. For Python: use module/file.py:app format when using runAppAs (WSGI/ASGI).

languageSpecificConfig

Language-specific packaging configuration.

Type: EsLanguageSpecificConfig or PyLanguageSpecificConfig or JavaLanguageSpecificConfig or PhpLanguageSpecificConfig or DotnetLanguageSpecificConfig or GoLanguageSpecificConfig or RubyLanguageSpecificConfig

requiresGlibcBinaries

Use glibc instead of musl (Alpine default). Enable if native dependencies require glibc.

Type: boolean

Results in a larger image. Common packages needing this: sharp, canvas, bcrypt, puppeteer.

customDockerBuildCommands

A list of commands to be executed during the docker build process.

Type: Array of string

These commands are executed using the RUN directive in the Dockerfile. This is useful for installing additional system dependencies in your container.

includeFiles

A glob pattern of files to explicitly include in the deployment package.

Type: Array of string

The path is relative to your Stacktape configuration file.

excludeFiles

A glob pattern of files to explicitly exclude from the deployment package.

Type: Array of string

excludeDependencies

A list of dependencies to exclude from the deployment package.

Type: Array of string

resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048

external-buildpack

The external-buildpack option builds an image using a zero-config external buildpack.

  • You can find a buildpack for almost any language or framework. The default buildpack is paketobuildpacks/builder:base. You can configure the buildpack using the buildpack property.
  • The buildpack scans the specified source directory and automatically determines how to build the image for your application.
  • The image is uploaded to a pre-created ECR repository.
ExternalBuildpackCwImagePackagingAPI reference
sourceDirectoryPathRequired

The path to the source code directory.

Type: string

builderDefault: paketobuildpacks/builder-jammy-base

The Buildpack Builder to use.

Type: string

buildpacks

The specific Buildpack to use.

Type: Array of string

By default, the buildpack is detected automatically.

command

A command to be executed when the container starts.

Type: Array of string

Example: ['/app/start.sh']

resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: external-buildpack
        properties:
          sourceDirectoryPath: ./src
          builder: heroku/buildpacks:20
      resources:
        cpu: 2
        memory: 2048

nixpacks

The nixpacks option builds an image using Nixpacks.

  • In most cases, building and deploying an application with Nixpacks requires no configuration.
  • Nixpacks scans the specified source directory and automatically determines how to build the image for your application.
  • The image is uploaded to a pre-created ECR repository.
NixpacksCwImagePackagingAPI reference
sourceDirectoryPathRequired

The path to the source code directory.

Type: string

buildImage

The base image to use for building the application.

Type: string

For more details, see the Nixpacks documentation.

providers

A list of providers to use for determining the build and runtime environments.

Type: Array of string

startCmd

The command to execute when starting the application.

Type: string

This overrides the default start command inferred by Nixpacks.

startRunImage

The base image to use for running the application.

Type: string

startOnlyIncludeFiles

A list of file paths to include in the runtime environment; all other files will be excluded.

Type: Array of string

phases

The build phases for the application.

Type: Array of NixpacksPhase

resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: nixpacks
        properties:
          sourceDirectoryPath: ./src
      resources:
        cpu: 2
        memory: 2048

custom-dockerfile

The custom-dockerfile option builds an image from your own Dockerfile.

  • You must configure buildContextPath. Stacktape will look for a Dockerfile in this directory (or use the one specified by dockerfilePath).
  • The image is uploaded to a pre-created ECR repository.
CustomDockerfileCwImagePackagingAPI reference
buildContextPathRequired

The path to the build context directory, relative to your Stacktape configuration file.

Type: string

entryPoint

A script to be executed when the container starts.

Type: Array of string

This overrides the ENTRYPOINT instruction in the Dockerfile.

dockerfilePath

The path to the Dockerfile, relative to buildContextPath.

Type: string

buildArgs

A list of arguments to pass to the docker build command.

Type: Array of DockerBuildArg

command

A command to be executed when the container starts.

Type: Array of string

This overrides the CMD instruction in the Dockerfile.

Example: ['/app/start.sh']

resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: custom-dockerfile
        properties:
          buildContextPath: ./server
          dockerfilePath: Dockerfile
      resources:
        cpu: 2
        memory: 2048

prebuilt-image

The prebuilt-image option uses a pre-built image.

  • To use private images, you must configure repositoryCredentialsSecretArn. The body of the secret should have the following format: {"username": "<<privateRegistryUsername>>", "password": "<<privateRegistryPassword>>"}.
  • Secrets can be managed with Stacktape. For more information, see the secrets documentation.
PrebuiltImageCwPackagingAPI reference
imageRequired

The name or URL of the container image.

Type: string

repositoryCredentialsSecretArn

The ARN of a secret containing credentials for a private container registry.

Type: string

The secret must be a JSON object with username and password keys. You can create secrets using the stacktape secret:create command.

entryPoint

A script to be executed when the container starts.

Type: Array of string

This overrides the ENTRYPOINT instruction in the Dockerfile.

command

A command to be executed when the container starts.

Type: Array of string

This overrides the CMD instruction in the Dockerfile.

Example: ['/app/start.sh']

resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: prebuilt-image
        properties:
          image: httpd:latest
      resources:
        cpu: 2
        memory: 2048

API reference

DockerBuildArgAPI reference
argNameRequired

Argument name

Type: string

valueRequired

Argument value

Type: string

EsLanguageSpecificConfigAPI reference
tsConfigPath

The path to the tsconfig.json file.

Type: string

This is primarily used to resolve path aliases during the build process.

emitTsDecoratorMetadata

Emit TypeScript decorator metadata. Required by NestJS, TypeORM, and similar frameworks.

Type: boolean

dependenciesToExcludeFromBundle

A list of dependencies to exclude from the main bundle.

Type: Array of string

These dependencies will be treated as "external" and will not be bundled directly into your application's code. Instead, they will be installed separately in the deployment package. Use * to exclude all dependencies from the bundle.

outputModuleFormatDefault: 'cjs'

Output module format: cjs (CommonJS) or esm (ES Modules, enables top-level await).

Type: string ENUM

Possible values: cjsesm

Note: Some npm packages don't support ESM. ESM may also produce less readable stack traces.

nodeVersionDefault: 18

The major version of Node.js to use.

Type: number ENUM

Possible values: 161718192021222324

disableSourceMaps

Skip generating source maps. Reduces package size but makes production errors harder to debug.

Type: boolean

outputSourceMapsTo

Save source maps to a local directory instead of uploading them to AWS.

Type: string

Useful for uploading to external error tracking (Sentry, Datadog, etc.). CloudWatch stack traces won't be mapped.

dependenciesToExcludeFromDeploymentPackage

A list of dependencies to exclude from the deployment package.

Type: Array of string

This only applies to dependencies that are not statically bundled. To exclude a dependency from the static bundle, use dependenciesToExcludeFromBundle. Use * to exclude all non-bundled dependencies.

PyLanguageSpecificConfigAPI reference
packageManagerFile

The path to your project's dependency file.

Type: string

This can be a requirements.txt, Pipfile, or pyproject.toml file.

packageManager

The Python package manager to use.

Type: string "uv"

Stacktape uses uv for dependency resolution and installation. This option is kept for compatibility and must be set to uv if provided.

pythonVersionDefault: 3.9

The version of Python to use.

Type: number ENUM

Possible values: 2.73.113.123.133.143.63.73.83.9

runAppAs

Python server type: WSGI (Flask, Django) or ASGI (FastAPI, Starlette).

Type: string ENUM

Possible values: ASGIWSGI

Only for stacktape-image-buildpack. Auto-binds to the PORT env var. Set entryfilePath to module/file.py:app (e.g., app/main.py:app).

minifyDefault: true

Minify Python code to reduce package size. Makes production stack traces harder to read.

Type: boolean

JavaLanguageSpecificConfigAPI reference
useMaven

Specifies whether to use Maven instead of Gradle.

Type: boolean

By default, Stacktape uses Gradle to build Java projects.

packageManagerFile

The path to your project's build file (pom.xml for Maven or build.gradle for Gradle).

Type: string

javaVersionDefault: 11

The version of Java to use.

Type: number ENUM

Possible values: 8111719