[caglarkc]

Issue # (if applicable)

Closes #21168.

Description

preCompilation hands the JavaScript entry point emitted by TypeScript to esbuild, but extensionless imports can still resolve to adjacent TypeScript sources. Those imported modules are then compiled without decorator metadata. Document the confirmed --resolve-extensions=.js workaround, the required compiler configuration, and its limitation that imported JavaScript must exist.

Validation

• The README example compiled and translated with jsii-rosetta (1 snippet, no diagnostics).
• A real TypeScript/esbuild reproduction confirms default extensionless imports lose imported decorator metadata and --resolve-extensions=.js preserves design:paramtypes at runtime.

Documentation only; no changes to bundling behavior or synthesized infrastructure.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license.

[maintainer-for-aws]

Automated review

A maintainer will still review this — treat the notes below as a starting point.

📌 Commit 4db5ef3

This PR is a documentation-only change to the aws-lambda-nodejs module. It adds five lines of JSDoc to the existing preCompilation property on BundlingOptions (lib/types.ts) and expands the "Pre Compilation with TSC" section of the README with a worked example showing how to set esbuildArgs: { '--resolve-extensions': '.js' } so that decorator metadata is preserved for imported modules during pre-compilation.

The change introduces no public API surface change, no signature change, and no synthesis or behavior change. The documented esbuildArgs usage is valid against the existing esbuildArgs?: { [key: string]: string | boolean } signature, and all referenced properties (preCompilation, tsconfig, entry) are real existing members, so the README example type-checks and carries no regression risk. No issues found on this change.

🔴 0 blocking · 🟡 0 recommended · ⚪ 0 optional

---

Generated automatically. React 👍 or 👎 to tell us whether this review helped, so we can improve these reviews.