The js-bundle packaging type (JsBundleLambdaPackaging) packages a JavaScript or TypeScript Lambda function from its entry file. Stacktape bundles the entry file and everything it imports into one minified file, installs the dependencies that cannot be bundled, and uploads the result. The bundle's source maps are stored in the stack's deployment bucket, outside the package.
js-bundle supports JavaScript and TypeScript only. For Python, Java, Go, Ruby, .NET and Rust functions, use buildpack.
When to use
Use js-bundle for every JavaScript or TypeScript Lambda function unless you already build the deployment package yourself: API handlers, event processors, scheduled tasks and webhooks.
Use custom-artifact instead when:
- You have a pre-built zip from a separate CI pipeline or build tool.
- Your build needs steps that the bundler does not support.
- You need to include artifacts generated outside your project tree.
For container resources (web services, worker services, multi-container workloads, batch jobs), see container js-bundle.
Basic example
entryfilePath is the only required property. It is relative to the Stacktape configuration file.
The handler file exports a function that AWS Lambda invokes:
Entry file
entryfilePath points to the file that contains the handler, relative to the Stacktape configuration file. Stacktape bundles the code starting from this file into one output file. Use dependenciesToExcludeFromBundle to keep selected packages out of the bundle. They are installed separately in the deployment package, which is often needed for packages with native binaries.
Handler function
The handlerFunction property names the exported function to execute when the Lambda is invoked. Set it when your entry file exports a specifically named handler function.
The memory and timeout properties in these examples are LambdaFunction settings, not packaging options — they are included here for realistic context.
The handler file would export the named function:
Including and excluding files
includeFiles, excludeFiles and excludeDependencies control what goes into the deployment package. Code is bundled starting from the entry file. Use includeFiles for runtime files that are not pulled in by the bundler, and excludeFiles to remove matched files from the deployment package. These options are useful when your function reads files at runtime that aren't statically imported (templates, configuration files, ML models, data files).
Including additional files
The includeFiles property explicitly includes files matched by glob patterns in the deployment package. Paths are relative to your Stacktape config file. Use this for any file your handler reads at runtime via the filesystem (e.g., fs.readFile) rather than through an import.
Excluding files
The excludeFiles property explicitly excludes files matched by glob patterns from the deployment package. This is useful when includeFiles globs are broader than intended, or when your project tree contains large files (test fixtures, documentation, local data) that would otherwise be included.
Excluding dependencies
The excludeDependencies property lists dependencies to exclude from the deployment package. Use it when you know a dependency is not needed at runtime. Smaller packages can reduce cold start times, so exclude dependencies you do not need at runtime.
Bundling options
All options are properties of JsBundleLambdaPackaging next to entryfilePath. See the API reference for the complete list.
How the bundle is built
Stacktape bundles your code starting from the entry file into a single output file. The bundle is minified (whitespace and syntax only, so function names stay readable in stack traces), and on Node.js 18 and later, imports of @aws-sdk/client-* and @aws-sdk/lib-* are left out of the package because the Lambda runtime provides them. Source maps are generated automatically and kept outside the package; see Source maps.
Source maps
Each deployment stores the function's source maps in the stack's deployment bucket instead of the deployment package, so the package carries code only. The maps contain no source code. When the Stacktape Console first sees an error from the function, it uses the maps of the code that threw to show the stack trace with the original file, line and function. Stack traces in CloudWatch logs point into the bundled code.
The deployment bucket keeps a function's maps as long as it keeps a deployment package that uses them, so the maps of every release you can roll back to stay available.
keepSourceMapsInPackage: trueships the maps in the package and turns on Node.js--enable-source-maps, so CloudWatch stack traces are mapped too. The package gets larger, and Node.js reads the maps on every cold start.outputSourceMapsToalso saves complete maps, original source included, to a local directory, for uploading to Sentry, Datadog or another tool.disableSourceMaps: truegenerates no maps; error locations then point into the bundled code everywhere.
Key options:
nodeVersion— major Node.js version used to build the bundle. Supported: 16, 17, 18, 19, 20, 21, 22, 23, 24. Default:24. This does not replace the Lambda resource'sruntime; set both to matching versions when overriding the default.outputModuleFormat—'cjs'(CommonJS) or'esm'(ES Modules, enables top-levelawait). Node.js 24 and later use ESM output; with earlier Node.js versions the default is CommonJS. Edge functions remain CommonJS. Some npm packages don't support ESM, and ESM may produce less readable stack traces.tsConfigPath— path to yourtsconfig.json, used to resolve path aliases during bundling.emitTsDecoratorMetadata— enable for frameworks that rely on TypeScript decorator metadata reflection (NestJS, TypeORM).dependenciesToExcludeFromBundle— packages treated as external (not bundled into the single output file). They're installed separately in the deployment package. Set the array to['*']to exclude all dependencies from the bundle.dependenciesToExcludeFromDeploymentPackage— removes non-bundled dependencies from the final package. Only applies to dependencies already excluded from the bundle. Set the array to['*']to exclude all non-bundled dependencies.disableSourceMaps— skips source map generation. Error locations then point into the bundled code.keepSourceMapsInPackage— keeps source maps in the deployment package and maps CloudWatch stack traces. Default:false. See Source maps.outputSourceMapsTo— also saves complete source maps to a local directory. Useful for external error tracking tools like Sentry or Datadog.minify— minifies the bundle (whitespace and syntax). Local function and variable names are kept, so stack traces and error messages stay readable. Default:true.minifyIdentifiers— also shortens local variable and function names. Slightly smaller bundle, but the names disappear from stack traces and error messages and change with every build, so Stacktape Console cannot group the same error across deployments. Default:false.bundleAwsSdk— bundles@aws-sdk/*from yournode_modulesinstead of using the copy the Lambda runtime provides. Enable it when you need a newer SDK than the runtime ships. Default:false.
This example sets both runtime: 'nodejs22.x' on the Lambda function and nodeVersion: 22 in its packaging config. The former selects the AWS Lambda runtime; the latter selects the Node.js version the bundle targets. Keep them aligned. Because Node.js 22 otherwise defaults to CommonJS, outputModuleFormat: 'esm' explicitly enables ES Module output. Use dependenciesToExcludeFromBundle for dependencies you do not want statically bundled — excluded dependencies are installed separately in the deployment package. An APM agent such as dd-trace needs this, because it instruments other modules as they load from node_modules. Setting tsConfigPath lets the bundler resolve TypeScript path aliases during bundling.
Use dependenciesToExcludeFromBundle for dependencies with native binaries. Excluded dependencies are installed separately in the deployment package rather than being statically bundled. This is the most common fix when a dependency works locally but fails in Lambda with a binary-related error.
Build caching
Stacktape caches deployment packages based on a checksum, so unchanged code is not re-packaged. This makes iterative deployments faster when only some functions have changed. Caching works automatically with no configuration needed.
Shared code between functions
When a stack has two or more JavaScript or TypeScript Lambda functions that can be packaged together, it builds them in a single pass and moves the npm dependencies they have in common into Lambda layers that those functions share. Your own shared modules stay in each function's package while they total 2 MB or less, so editing them deploys as a code update, as fast as editing a handler, without publishing a new layer version. When a shared module runs setup code as it loads (for example, it sets process.env or starts tracing) before packages load, the packages and your modules stay in the shared layers together, so they still load in the original order. Nothing needs to be configured, and your imports do not change.
The effect grows with the number of functions. Twenty-five functions that share a library and the AWS SDK produce twenty-five small packages plus one layer, instead of twenty-five packages that each carry a full copy of the shared code.
Stacktape creates at most three layers, leaving two of Lambda's five layer slots for layers you attach yourself. Code that only one function uses is never moved into a layer.
When a function is packaged on its own
A function is packaged individually, without a shared layer, when it uses an option the shared build cannot honor:
- tracing is enabled for it (its handler is wrapped at the bundle entry)
outputModuleFormat: 'cjs'emitTsDecoratorMetadata: trueoutputSourceMapsTodependenciesToExcludeFromDeploymentPackageincludeFilesorexcludeFiles- a
nodeVersionother than 18, 20, 22 or 24
Functions also have to agree with each other to share a build. Architecture, nodeVersion, tsConfigPath, disableSourceMaps, keepSourceMapsInPackage, minify, minifyIdentifiers, bundleAwsSdk, dependenciesToExcludeFromBundle and excludeDependencies must match; functions that differ are grouped separately. The largest group shares a build and the rest are packaged individually, so one unusual function no longer costs the others their shared layer.
Changing your own shared code changes the package of every function that uses it, and the layers stay as they are. Changing one handler's own code changes only that one package. Changing a shared npm dependency publishes a new layer version.
Processor architecture
JsBundleLambdaPackaging does not expose an architecture setting. Configure architecture on the Lambda function resource; see that page for details. If your function uses native binary dependencies, verify they ship builds compatible with your chosen architecture before switching.
API reference
JsBundleLambdaPackagingPropsJS Bundle for Lambda FAQ
Should I use js-bundle or a custom artifact?
Use js-bundle for most projects. It handles bundling and artifact creation with minimal configuration. Use custom artifact packaging when you already have a pre-built zip from an external build pipeline, need a custom toolchain the bundler doesn't support, or want full control over the deployment package contents.
Can I use ES Modules (ESM)?
Yes. Node.js 24 and later use ES Module output automatically. With an earlier Node.js version, set outputModuleFormat: 'esm'; ESM also enables top-level await. Edge functions remain CommonJS. Some npm packages don't support ESM, and ESM can produce less readable stack traces — test your function after switching to catch compatibility issues.
What is the maximum Lambda deployment package size?
AWS Lambda allows 250 MB unzipped for a function and all its layers together. Its 50 MB zipped limit applies only to direct uploads; Stacktape deploys code through S3, so it doesn't apply. js-bundle keeps packages small on its own: it bundles to a single minified file, leaves the runtime-provided AWS SDK out, and moves code shared between functions into a shared layer. excludeFiles and excludeDependencies trim further. If your dependencies still cannot fit, consider moving the workload to a container resource such as a web service, worker service, or batch job.
How do I handle native binary dependencies like sharp or Prisma?
Usually you don't need to do anything. Stacktape detects packages that load native binaries or read their own files at run time, keeps them out of the bundle and installs them for the function's platform. Prisma's client is bundled, and the function gets the query engine for its architecture. With Prisma 5 or 6, add rhel-openssl-3.0.x (x86_64) or linux-arm64-openssl-3.0.x (arm64) to binaryTargets in schema.prisma; Prisma 7 needs no engine. If a dependency still works locally but fails in Lambda, add it to dependenciesToExcludeFromBundle to install it beside the bundle.
My function runs an older AWS SDK than the one in my package.json — why?
On Node.js 18 and later, the Lambda runtime ships the AWS SDK v3, and js-bundle leaves @aws-sdk/client-* and @aws-sdk/lib-* imports out of the package so they resolve from the runtime. The runtime's copy can lag behind npm. If your code needs a newer SDK, set bundleAwsSdk: true to bundle the version from your node_modules.
Why does my stack contain Lambda layers I did not configure?
When several functions can be packaged together, Stacktape moves the code they share into layers so each package carries only its own code. This is automatic. See shared code between functions for what goes into a layer and which options keep a function off that path.
How do I debug a function packaged with js-bundle?
The Stacktape Console shows each runtime error with the original file, line and function, read from the source maps the deployment stored in your deployment bucket. CloudWatch logs show positions in the bundled code; set keepSourceMapsInPackage: true to have Node.js map them as well. For rapid iteration without a full redeploy, use dev mode with Lambda functions.