The js-bundle packaging type (JsBundleImagePackaging) builds a container image from a JavaScript or TypeScript entry file. Stacktape bundles the entry file and everything it imports into one file, installs only the dependencies that cannot be bundled, and uploads the image to a managed ECR repository. No Dockerfile is needed.
It applies to web services, private services, worker services, multi-container workloads, batch jobs and AgentCore runtimes.
js-bundle supports JavaScript and TypeScript only. For Python, Java, Go, Ruby, PHP, .NET, Rust and other languages, use buildpack.
When to use
Use js-bundle for Node.js services with a single entry file: Express, Hono, Fastify, NestJS or plain Node.js workers. The image is small because it contains one bundled file and the few dependencies that must stay on disk.
Use another packaging type when:
- Your app is not a single bundled entry file. Frameworks such as Next.js, Nuxt or Remix produce their own build output. Use
buildpack, which runs the framework's build and start commands. - The project is not JavaScript or TypeScript. Use
buildpack. - You need full control over the image. Use
dockerfilefor a custom base image, multi-stage builds or a custom entrypoint. - The image already exists. Use
prebuilt-image.
Basic example
entryfilePath is the only required property. It is relative to the Stacktape configuration file.
The cpu and memory values belong to the web service, not to packaging. See web service for valid values.
How the image is built
- Stacktape bundles the entry file and its imports into one file with source maps.
- Dependencies that cannot be bundled are installed in Docker. These are packages with native binaries and packages listed in
dependenciesToExcludeFromBundle. - The bundle and those dependencies are copied into an Alpine-based Node.js image.
- The image is pushed to a managed ECR repository.
The image holds the runtime and your code, with nothing else installed:
- No init process in the image. ECS and AWS Batch start one as PID 1 (
initProcessEnabled). It passes the stop signal to your server and reaps orphaned processes. An AgentCore runtime cannot start one, so its image getstini. - curl only for health checks. When the container's
internalHealthCheckcommand callscurl, the image installs it. BusyBoxwgetis always available on Alpine. - OpenSSL. The Alpine image already has the OpenSSL 3 libraries that Prisma and other native packages load. When your code, or a package installed beside the bundle, uses Prisma, it also gets the
opensslcommand, which Prisma 5 needs to choose its query engine. The glibc image (requiresGlibcBinaries) installsopenssl. Install anything else, such as theopensslcommand for your own code, withcustomDockerBuildCommands. - Prisma query engine. Prisma's client is bundled, and the image gets only the query engine its platform loads. With Prisma 5 or 6, add that engine to
binaryTargetsinschema.prisma:linux-musl-openssl-3.0.xfor the Alpine image,debian-openssl-3.0.xfor the glibc, Bun and Deno images, andlinux-musl-arm64-openssl-3.0.xorlinux-arm64-openssl-3.0.xon arm64. Prisma 7 needs no engine.
Artifacts are cached by a checksum of their inputs. When the code and dependencies have not changed, Stacktape does not build the image again.
Bundling options
All options are properties of JsBundleImagePackaging next to entryfilePath.
dependenciesToExcludeFromBundle: ['dd-trace'] is an example: an APM agent instruments other modules as they load from node_modules. List the packages your application cannot bundle, or omit the property. Native packages, packages that read their own files and Prisma's client work without it.
Module format
outputModuleFormat sets the bundle output to CommonJS ('cjs') or ES Modules ('esm'). When omitted, Node.js 24 and later use ESM and earlier versions use CommonJS. ESM enables top-level await. Some npm packages do not support ESM, and ESM stack traces can be less readable.
Node.js version
nodeVersion selects the Node.js major version of the image. Supported values are 16 to 24. The default is 24.
Bun and Deno
runtime selects the JavaScript runtime of the image: node (default), bun or deno. With bun, the bundle targets Bun and runs on the official oven/bun:1 image with bun index.js. With deno, the bundle runs on the pinned denoland/deno 2.9 Debian image with deno run --allow-all index.js. Dependencies that cannot be bundled are installed with the runtime's own package manager (bun add, deno add npm:). nodeVersion has no effect on these runtimes. Lambda functions have no runtime option here; they run on the Node.js runtime.
TypeScript decorator metadata
Set emitTsDecoratorMetadata: true if the project uses decorators with runtime metadata. NestJS, TypeORM and other frameworks that rely on reflect-metadata need it.
TypeScript path aliases
tsConfigPath points to the tsconfig.json that the bundler reads to resolve path aliases such as @/lib/db.
Native and excluded dependencies
dependenciesToExcludeFromBundle keeps packages out of the bundle. They are installed in the image instead. Use it for packages that break when bundled: ORMs with dynamic imports, packages that locate files through __dirname, and native add-ons. ['*'] excludes all dependencies from the bundle.
dependenciesToExcludeFromDeploymentPackage removes non-bundled packages from the image entirely. Use it only for packages that are never needed at runtime. ['*'] removes all non-bundled dependencies.
Source maps
Source maps are generated by default. disableSourceMaps: true skips them, which makes the image smaller and production errors harder to read. outputSourceMapsTo saves the maps to a local directory for an external error tracker such as Sentry; CloudWatch stack traces are then not mapped.
Minification
The bundle is minified by default. Whitespace and syntax are shortened, but local function and variable names are kept, so stack traces stay readable. minifyIdentifiers: true also shortens those names for a slightly smaller image. The names then change with every build, and Stacktape Console cannot group the same error across deployments. minify: false deploys the code unminified.
Image customization
Using glibc instead of Alpine musl
The image is based on Alpine Linux, which uses musl libc. Some native dependencies need glibc, for example sharp, canvas, bcrypt and puppeteer. Set requiresGlibcBinaries: true to use a glibc-based image. The image is larger, so enable it only when you see errors such as Error loading shared library or GLIBC_X.XX not found.
Custom Docker build commands
customDockerBuildCommands adds shell commands to the image build. Each string runs as a RUN instruction. Use it to install system packages or add build-time files.
apk add works on the default Alpine image. With requiresGlibcBinaries: true the image is not Alpine, so use that image's package manager instead.
File inclusion and exclusion
includeFiles and excludeFiles take glob patterns relative to the Stacktape configuration file. excludeDependencies removes named packages from the image.
includeFilesadds files that the code reads at runtime but does not import, such as templates or static assets.excludeFilesremoves files the service does not need, such as tests and development configuration.excludeDependenciesremoves packages that are not needed at runtime.
Comparison with other container packaging types
js-bundle | buildpack | dockerfile | prebuilt-image | |
|---|---|---|---|---|
| Languages | JavaScript, TypeScript | Detected: Node.js, Python, Go, Rust, Java, PHP, Ruby, .NET and more | Any | Any |
| Dockerfile needed | No | No | Yes | No |
| Input | Entry file | Project directory | Dockerfile and build context | Image reference |
| Start command | Generated from the bundle | Detected or startCommand | command, entryPoint | command, entryPoint |
| Base image | Alpine (or glibc) | Debian | Your choice | Your choice |
JS Bundle for Containers FAQ
Where are built images stored, and what does it cost?
Stacktape uploads each image to a managed ECR repository. You do not create or configure it. ECR charges for image storage and data transfer out, so smaller images cost less. Keep the default Alpine image unless a dependency needs glibc, and remove tests and development files with excludeFiles.
Can I set a custom start command?
No. The container runs the bundled entry file. If you need a different start command, use buildpack with startCommand, or dockerfile with command and entryPoint.
How do I install system packages in the image?
Use customDockerBuildCommands. On the default Alpine image, use apk add --no-cache <package>. This covers tools such as ffmpeg, native crypto libraries and database clients.
API reference
JsBundleCwImagePackagingProps