aws / aws/agentcore-cli

bug: agentcore package fails for TypeScript because esbuild is bundled

Open
#2,125 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
TypeScript
Stars
283
Forks
95
Avg merge
1d 2h
Merged PRs (30d)
183

Description

### Description

`agentcore package` fails when packaging a TypeScript CodeZip project because the CLI bundle includes esbuild's JavaScript API.

I encountered this with `@aws/agentcore` versions `0.27.1` and `0.28.0`.

### Steps to Reproduce

1. Use an unmodified npm installation of `@aws/agentcore@0.28.0`.
2. Create a minimal project with the following files.

`agentcore/agentcore.json`:

```json
{
"name": "PackageTest",
"version": 1,
"runtimes": [
{
"name": "TestRuntime",
"build": "CodeZip",
"entrypoint": "main.ts",
"codeLocation": "./app/TestRuntime",
"runtimeVersion": "NODE_22",
"protocol": "HTTP"
}
]
}
```

`app/TestRuntime/main.ts`:

```typescript
export {};
```

`app/TestRuntime/package.json`:

```json
{
"name": "typescript-package-fixture",
"version": "1.0.0",
"private": true
}
```

3. From the project root, run:

```bash
agentcore package
```

### Expected Behavior

The command successfully bundles the TypeScript entry point and creates `agentcore/TestRuntime.zip`.

### Actual Behavior

Packaging fails with:

```text
The esbuild JavaScript API cannot be bundled.
Please mark the "esbuild" package as external so it's not included in the bundle.
```

### CLI Version

0.28.0

### Operating System

macOS

### Additional Context

The original environment used Node.js `v24.15.0`.

In `esbuild.config.mjs`, `esbuild` is not listed as an external dependency, so its JavaScript API is bundled into the CLI. TypeScript CodeZip packaging invokes that API at runtime.

Marking `esbuild` as external alone is insufficient: it is currently a development dependency, so an npm installation of the published CLI does not install it as a direct runtime dependency.

I have prepared a patch that:

* Marks `esbuild` as external in the CLI build.
* Moves `esbuild` from `devDependencies` to `dependencies`, retaining the existing version range and updating `npm-shrinkwrap.json`.
* Extends the existing installed-tarball smoke test to package a minimal TypeScript fixture and check that the ZIP is generated.

In a separate clean installation from an npm-packed tarball, the unpatched CLI failed with the error above, while the patched CLI successfully generated the ZIP.

This report concerns local packaging; no AWS deployment is required to reproduce it.

Contributor guide

Open the contributing guide

Research direction

Start with esbuild.config.mjs and the package manifest to trace how the CLI bundles and installs esbuild. Review the npm-shrinkwrap.json changes and extend the existing installed-tarball smoke test with the minimal TypeScript fixture described here. Done means a clean npm-packed installation runs agentcore package and creates the expected ZIP without the bundling error.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
build-system, cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.