fix(esbuild): support compose root dependencies with packages external by czubocha · Pull Request #13742 · serverless/serverless

czubocha · Jul 24, 2026

Summary

Fix a TypeError: Cannot convert undefined or null to object crash in packages/serverless/lib/plugins/esbuild/index.js (_preparePackageJson) when a service inside a Serverless Compose project has no package.json of its own (or none with a dependencies field) and sets build.esbuild.packages: external
With packages: external, a service that declares its own dependencies keeps exactly those (unchanged behavior); a service that declares none now falls back to the package.json next to serverless-compose.yml, so the deployment archive gets a working node_modules instead of a crash
Document dependency-version resolution for externals, including the Compose-root fallback, in docs/sf/providers/aws/guide/building.md

Root cause

When packaging inside a Compose project, _preparePackageJson enters its dependency-processing branch if either the service or the compose-root package.json declares dependencies. The packages: external path kept only the service's dependencies and skipped initializing the rewritten dependencies object, so with no service dependencies the subsequent exclude-cleanup loop (the @aws-sdk/* default is always present) dereferenced undefined and crashed the package/deploy command.

Backward compatibility

The change is scoped to configurations that previously crashed. Every configuration that packaged successfully before produces identical output: outside Compose nothing changes, and inside Compose a service with its own dependencies never consults the compose root under packages: external. This deliberately includes a service declaring an explicitly empty "dependencies": {} — that configuration packaged successfully before (producing empty node_modules), so it keeps doing exactly that rather than pulling in the compose-root dependencies; a dedicated unit test pins this contract.

Test plan

New unit tests in packages/serverless/test/unit/lib/plugins/esbuild/prepare-package-json.test.js: crash case (compose + no service package.json + packages: external), service-declared dependencies remain exactly as before (compose root not merged), non-compose packages: external unchanged, bundling-path compose fallback unchanged
Full packages/serverless unit suite passes (160 suites, 2893 tests)
Live check from source CLI: compose project with root-only package.json and packages: external — previously crashed, now packages successfully with the root dependencies in node_modules; the same project with a service-level package.json produces a zip containing only the service's dependencies (root packages absent), matching pre-fix output

How to test

In a Compose project where only the root (next to serverless-compose.yml) has a package.json:

# service serverless.yml
build:
  esbuild:
    packages: external

serverless <service> package

Before: crashes with TypeError: Cannot convert undefined or null to object. After: packaging succeeds and the function zip contains node_modules with the compose-root dependencies.

Summary by CodeRabbit

Bug Fixes
- Improved AWS Lambda packaging for esbuild when using external packages, ensuring dependencies are correctly included in the deployment archive’s node_modules.
- Preserved a service’s own dependency list (including an explicitly empty dependencies) when packages: "external" is enabled.
- Added clearer fallback behavior for external dependencies using the Compose root when the service doesn’t declare dependencies.
Documentation
- Clarified how external dependencies are resolved and included for AWS Lambda builds (including Compose behavior).
Tests
- Added/updated unit coverage for packages: "external" in both Compose and non-Compose scenarios.

Mmarzex · Jul 24, 2026

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

coderabbitai · Jul 24, 2026

📝 Walkthrough

Walkthrough

External esbuild packaging now writes service dependencies for packages: external, falls back to Compose-root dependencies when needed, documents the resolution behavior, and adds unit coverage for Compose and non-Compose scenarios.

Changes

External dependency preparation

Layer / File(s)	Summary
External dependency resolution `packages/serverless/lib/plugins/esbuild/index.js`, `docs/sf/providers/aws/guide/building.md`	`_preparePackageJson` preserves service dependencies or falls back to Compose-root dependencies, and the AWS guide documents external dependency installation and resolution.
Dependency resolution coverage `packages/serverless/test/unit/lib/plugins/esbuild/prepare-package-json.test.js`	Tests cover Compose fallback, service dependency precedence, explicit empty dependencies, non-Compose packaging, configured externals, mocked installation, and temporary fixture cleanup.

Estimated code review effort: 2 (Simple) | ~15 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main fix: esbuild now supports compose-root dependencies when `packages: external` is enabled.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/esbuild-compose-packages-external

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/serverless/lib/plugins/esbuild/index.js`:
- Around line 1195-1197: Update the dependency selection in the package JSON
assembly flow so `packageJson.dependencies` is used only when it contains at
least one key; otherwise fall back to `composePackageJson.dependencies`. Add a
regression test covering a Compose service with an empty dependencies object and
verify root dependencies are included in the archive.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c209b06-bc22-4388-9085-2e1ce2843c61

📥 Commits

Reviewing files that changed from the base of the PR and between bd9ed54 and 501a0e7.

📒 Files selected for processing (3)

docs/sf/providers/aws/guide/building.md
packages/serverless/lib/plugins/esbuild/index.js
packages/serverless/test/unit/lib/plugins/esbuild/prepare-package-json.test.js

…lback

fix(esbuild): support compose root dependencies with packages external

501a0e7

coderabbitai Bot reviewed Jul 24, 2026

View reviewed changes

Comment thread packages/serverless/lib/plugins/esbuild/index.js

test(esbuild): pin backward-compat contract for packages external fal…

3d68b83

…lback

czubocha merged commit f2c08df into main Jul 24, 2026
12 checks passed

czubocha deleted the fix/esbuild-compose-packages-external branch July 24, 2026 15:12

github-actions Bot locked and limited conversation to collaborators Jul 24, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(esbuild): support compose root dependencies with packages external#13742

fix(esbuild): support compose root dependencies with packages external#13742
czubocha merged 2 commits into
mainserverless/serverless:mainfrom
fix/esbuild-compose-packages-externalserverless/serverless:fix/esbuild-compose-packages-externalCopy head branch name to clipboard

czubocha commented Jul 24, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

Mmarzex commented Jul 24, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 24, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Search code, repositories, users, issues, pull requests...

Uh oh!

Conversation

czubocha commented Jul 24, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root cause

Backward compatibility

Test plan

How to test

Related

Summary by CodeRabbit

Uh oh!

Mmarzex commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Snyk checks have passed. No issues have been found so far.

Uh oh!

coderabbitai Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

czubocha commented Jul 24, 2026 •

edited by coderabbitai Bot

Loading

Mmarzex commented Jul 24, 2026 •

edited

Loading

coderabbitai Bot commented Jul 24, 2026 •

edited

Loading