Custom Artifact

Custom artifact packaging lets you bring a pre-built Lambda deployment package to Stacktape. Point packagePath at a zip file, a directory, or a non-zip file — Stacktape automatically zips directories and non-zip files, then deploys the result. This packaging mode applies only to Lambda function resources.

When to use

Choose custom artifact packaging when:

  • Your CI/CD pipeline already produces a deployment zip and you want Stacktape to deploy it without re-bundling.
  • You need full control over what goes into the package — native binaries, pre-compiled assets, vendored dependencies.
  • You're migrating an existing Lambda project to Stacktape and want to keep your existing build step unchanged.
  • You have a custom build process and need full control over what gets packaged.

When NOT to use

Skip custom artifact packaging if you don't have a custom build step. For JavaScript and TypeScript, js-bundle bundles the code into a single file with source maps from an entry file path. For Python, Java, Go, Ruby, .NET and Rust, buildpack installs dependencies and compiles the code for you.

Use js-bundle or buildpack if you want Stacktape to manage the build. Use custom artifact if you manage the build yourself.

Basic example

Specify packagePath and handler in the packaging, and runtime on the Lambda resource:

export default defineConfig(() => {
  const api = new LambdaFunction({
    packaging: new CustomArtifactLambdaPackaging({
      packagePath: './dist/lambda.zip',
      handler: 'index.js:default'
    }),
    runtime: 'nodejs22.x'
  });

  return {
    resources: { api }
  };
});

Configuration

CustomArtifactLambdaPackaging exposes two required properties: packagePath and handler. All other Lambda runtime settings (memory, timeout, environment variables, etc.) are configured on the Lambda function resource itself, not on the packaging.

packagePath

The packagePath property is required alongside handler and the Lambda resource's runtime. It specifies the path to your pre-built deployment package.

Stacktape accepts three input shapes:

Input typeBehavior
A .zip fileDeployed directly
A directoryAutomatically zipped before deployment
A non-zip fileAutomatically zipped before deployment

You don't need to zip your output manually if your build produces a directory. Point packagePath at the directory and Stacktape handles the zipping.

handler

The handler property tells Lambda which function to invoke when the Lambda is triggered. The syntax is filepath:functionName.

For example, index.js:default invokes the default export from index.js at the artifact root, and handlers/process.js:main invokes main from handlers/process.js. Stacktape turns the path into Lambda's handler format by dropping the file extension: handlers/process.main.

Java and .NET artifacts use Lambda's own handler format, which Stacktape passes through as written: com.example.Handler::handleRequest for Java, Assembly::Namespace.Class::Method for .NET.

Set handler here and runtime on the Lambda resource: Stacktape does not infer them from the artifact.

export default defineConfig(() => {
  const processor = new LambdaFunction({
    packaging: new CustomArtifactLambdaPackaging({
      packagePath: './build/output',
      handler: 'process.js:main'
    }),
    runtime: 'nodejs22.x',
    memory: 512,
    timeout: 60
  });

  return {
    resources: { processor }
  };
});

In this example, packagePath points to a directory. Stacktape zips it automatically, and Lambda invokes the main export from process.js at the root of the resulting package. The memory and timeout properties are Lambda function settings, not part of the packaging configuration.

Using with a custom build step

Custom artifact packaging works well with an external build step in your CI pipeline or local workflow. Run your build tool to produce the artifact, then point packagePath at the output.

Make sure the build runs before stacktape deploy so that packagePath contains the artifact you intend to release.

A typical CI workflow:

npm run build
stacktape deploy --stage production

The build step is entirely decoupled from Stacktape — Stacktape reads the artifact at packagePath at deploy time.

Directory packaging example

Custom artifact packaging accepts directories as input. When your build produces a directory, point packagePath at the directory root:

export default defineConfig(() => {
  const fn = new LambdaFunction({
    packaging: new CustomArtifactLambdaPackaging({
      packagePath: './lambda-build',
      handler: 'app.py:handler'
    }),
    runtime: 'python3.12',
    memory: 256,
    timeout: 30
  });

  return {
    resources: { fn }
  };
});

Stacktape zips the directory before deployment. Make sure the file referenced by handler is located at the expected path inside the package — in this case, app.py must be at the root of the ./lambda-build directory. As with the previous example, memory and timeout are Lambda function settings configured alongside packaging.

Comparison with other Lambda packaging types

custom-artifactjs-bundlebuildpack
Build responsibilityYou build the artifactStacktape bundles from sourceStacktape builds from source in Docker
ConfigurationpackagePath + handler + resource runtimeentryfilePath + bundling optionsentryfilePath + runtime + language options
Supported languagesAny language the Lambda runtime supportsJavaScript, TypeScriptPython, Java, Go, Ruby, .NET, Rust
Source mapsYour responsibilityAutomaticNot applicable
Shared code between functionsYour responsibilityMoved into a shared Lambda layer automaticallyNot shared
Best forCustom build processes, pre-built CI artifactsNode.js functionsOther languages with standard dependency files

All three packaging types produce a Lambda deployment package. The difference is who builds the artifact: you or Stacktape.

Custom Artifact FAQ

When should I use custom artifact instead of js-bundle or buildpack?

Use custom artifact packaging when your project has a custom build process that Stacktape can't replicate, or when your CI pipeline already produces a tested zip and you want Stacktape to deploy it directly. For standard TypeScript or Python code, js-bundle and buildpack are simpler.

Do I have to zip my artifact myself?

No. packagePath accepts a .zip file, a directory, or any single non-zip file (for example, a compiled Go binary). A .zip is deployed as-is; a directory or non-zip file is zipped automatically before deployment — convenient when your build tool outputs a folder or a single binary rather than a ready-made zip.

What value do I set for the handler property?

The handler property uses filepath:functionName syntax and points at the file inside the deployment package, not your source. For a TypeScript Lambda compiled to JavaScript, reference the output .js, not the source .ts — if your build emits dist/index.js with an exported handler, set handler: 'index.js:handler' and point packagePath at dist.

Why does my custom artifact deploy but fail at runtime?

The most common cause is a handler path that doesn't match the file structure inside your zip. Unzip the artifact locally and confirm the handler file exists at the path Lambda will see — a mismatch typically surfaces as a module-not-found or handler-not-found error at invocation time. Use stacktape logs to view the error.

CustomArtifactLambdaPackagingProps
Click a property in the tree to see its description, default value, and full type.