[cli] Migrate build output from CommonJS to ESM by tknickman · Pull Request #14566 · vercel/vercel

tknickman · 2026-01-09T15:06:23Z

Summary

This PR migrates the Vercel CLI build output from CommonJS to ESM (ECMAScript Modules), enabling the use of modern ESM-only packages while maintaining full backwards compatibility.

Key Changes

Build Configuration: Added "type": "module" to package.json, updated esbuild to output ESM format with a CJS compatibility shim for require, __filename, and __dirname
Worker Files: Renamed standalone worker files (builder-worker.js, get-latest-worker.js) to .cjs extension since they use CommonJS syntax
Template Compilation: Updated doT.js template compilation to handle ESM package context
TypeScript Config: Updated module settings to esnext with node16 resolution
Jest Config: Renamed to .cjs for CommonJS compatibility in ESM package

Why ESM?

Enables use of modern npm packages that are ESM-only (e.g., Ink 5+/6+ for terminal UI)
Better tree-shaking and static analysis capabilities
Aligns with the Node.js ecosystem direction
Prerequisite for future CLI enhancements

Backwards Compatibility

This change is fully backwards compatible:

CLI works identically for end users
All existing functionality preserved
Works with both Node.js and Bun runtimes
No changes to public API or CLI interface

Test plan

pnpm build --filter=vercel succeeds
vercel --version works correctly
vercel whoami works correctly
vercel dev --help loads without errors
Unit tests pass (1,582 passing)
Works with Node.js runtime
Works with Bun runtime

🤖 Generated with Claude Code

changeset-bot · 2026-01-09T15:06:28Z

🦋 Changeset detected

Latest commit: 50c773f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
vercel	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-01-09T15:07:43Z

🧪 Test Strategy

Comparing: 8356799 → 50c773f (view diff)

Strategy: Code changed outside of a package - running ALL tests

⚠️ All tests will run because global code changes could impact all packages.

Affected packages - 16 (40%)

@vercel-internals/get-package-json
@vercel/next
vercel
@vercel/build-utils
@vercel/client
@vercel/firewall
@vercel/fs-detectors
@vercel/go
@vercel/hydrogen
@vercel/node
@vercel/python
@vercel/remix-builder
@vercel/ruby
@vercel/rust
@vercel/static-build
examples

Unaffected packages - 24 (60%)

@vercel/backends
@vercel/cervel
@vercel/cli-auth
@vercel/config
@vercel/detect-agent
@vercel/edge
@vercel/elysia
@vercel/error-utils
@vercel/express
@vercel/fastify
@vercel/frameworks
@vercel/functions
@vercel/gatsby-plugin-vercel-builder
@vercel/h3
@vercel/hono
@vercel/introspection
@vercel/nestjs
@vercel/oidc
@vercel/oidc-aws-credentials-provider
@vercel/python-analysis
@vercel/redwood
@vercel/related-projects
@vercel/routing-utils
@vercel/static-config

Results

Unit tests: All affected packages will run unit tests
E2E tests: All e2e tests will run
Type checks: All affected packages will run type checks

This comment is automatically generated based on the affected testing strategy

TooTallNate · 2026-01-09T17:37:56Z

:nice-90s-bounce:

mehulkar

cool, let me know if you want to do more testing (not even sure how that happens)

github-actions · 2026-01-12T14:57:06Z

📦 CLI Tarball Ready

The Vercel CLI tarball for this PR is now available!

Quick Test

You can test this PR's CLI directly by running:

npx https://vercel-aayd39b0d.vercel.sh/tarballs/vercel.tgz --help

Use in vercel.json

To use this CLI version in your project builds, add to your vercel.json:

{
  "build": {
    "env": {
      "VERCEL_CLI_VERSION": "vercel@https://vercel-aayd39b0d.vercel.sh/tarballs/vercel.tgz"
    }
  }
}

This change updates the CLI build process to output ESM (ECMAScript Modules) instead of CommonJS, while maintaining full backwards compatibility. - Add `"type": "module"` to package.json - Update esbuild to output `format: 'esm'` - Add banner shim for CommonJS globals (`require`, `__filename`, `__dirname`) - Update tsconfig.json with `module: 'esnext'` and `moduleResolution: 'node16'` - Rename `builder-worker.js` → `builder-worker.cjs` - Rename `get-latest-worker.js` → `get-latest-worker.cjs` - These standalone worker files use CommonJS and need explicit `.cjs` extension - Update `compile-templates.mjs` to handle doT.js output in ESM context - Rename generated files to `.cjs` before requiring them - Rename `jest.config.js` → `jest.config.cjs` for CommonJS compatibility - Add `.gitignore` entries to prevent test-generated artifacts from being tracked - Enables use of modern npm packages that are ESM-only - Better tree-shaking and static analysis - Aligns with Node.js ecosystem direction - Prerequisite for future enhancements (e.g., Ink for terminal UI) This change is fully backwards compatible: - CLI works identically for end users - All existing functionality preserved - Works with both Node.js and Bun runtimes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

The start.js script used require() which fails with "type": "module". Convert to dynamic import() to fix test failures. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

The module and moduleResolution settings are not needed since esbuild handles module resolution during bundling. The node16 moduleResolution was causing tsc --noEmit to fail because it requires explicit .js extensions in import paths. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

In ESM, callSite.getFileName() returns a file:// URL instead of a regular file path. This caused path.join to malform the path and the package.json lookup to fail. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Without await, the script could exit before the imported module finishes executing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

enableCompileCache was added in Node.js 22.1.0. The static import fails on Node 20 because the export doesn't exist. Using dynamic import with try-catch allows graceful degradation on older versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Test fixtures were being treated as ES modules because Node.js was walking up the directory tree and finding the CLI's package.json with type: module. This caused Lambda functions to fail with require is not defined in ES module scope errors. The fix adds type: commonjs to: - packages/cli/test/dev/fixtures/package.json (new file) - packages/cli/test/fixtures/package.json (existing file) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add tests to validate ESM migration behavior: - CJS shim globals (require, __filename, __dirname) - enableCompileCache backward compatibility pattern - Worker file resolution and CommonJS syntax - file:// URL handling for ESM stack traces - Test fixture isolation from ESM inheritance Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Use platform-specific paths instead of hardcoded Unix paths. fileURLToPath behaves differently on Windows (adds drive letter). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Set module to es2022 to enable import.meta support for ESM unit tests while maintaining compatibility with existing code that doesnt use explicit file extensions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Explain why we rename to .cjs (ESM package needs explicit CJS extension) and why we delete instead of rename back (generating TypeScript instead). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Replace createRequire/require() with await import() which works with both ESM and CJS modules natively, simplifying the code. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-authored-by: Steven <steven@ceriously.com>

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## vercel@50.3.0 ### Minor Changes - Add upgrade command ([#14584](#14584)) - Support typo detection for commands as well as frameworks ([#14586](#14586)) ### Patch Changes - Migrate CLI build output from CommonJS to ESM ([#14566](#14566)) - Change CLI package to use ESM format (`"type": "module"`) - Add ESM shim banner for CommonJS compatibility (`require`, `__filename`, `__dirname`) - Rename worker files to `.cjs` extension for explicit CommonJS handling - Fix `getPackageJSON` to handle ESM `file://` URLs from stack traces - Convert `scripts/start.js` to use dynamic import ## @vercel/python-analysis@0.1.1 ### Patch Changes - Fix release ([#14591](#14591)) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

tknickman requested a review from a team as a code owner January 9, 2026 15:06

vercel Bot deployed to Preview January 9, 2026 15:07 View deployment

vercel Bot deployed to Preview January 9, 2026 15:20 View deployment

vercel Bot reviewed Jan 9, 2026

View reviewed changes

Comment thread packages/cli/scripts/start.js Outdated

vercel Bot deployed to Preview January 9, 2026 15:25 View deployment

vercel Bot deployed to Preview January 9, 2026 15:37 View deployment

vercel Bot deployed to Preview January 9, 2026 17:16 View deployment

vercel Bot deployed to Preview January 9, 2026 17:20 View deployment

vercel Bot deployed to Preview January 9, 2026 17:27 View deployment

vercel Bot deployed to Preview January 9, 2026 18:39 View deployment

vercel Bot deployed to Preview January 9, 2026 19:09 View deployment

tknickman force-pushed the tknickman/cli-esm-migration branch from bae3b13 to 1dc8691 Compare January 9, 2026 19:20

vercel Bot deployed to Preview January 9, 2026 19:21 View deployment

tknickman requested review from TooTallNate, anthonyshew, jeffsee55 and styfle January 9, 2026 19:33

vercel Bot deployed to Preview January 9, 2026 19:45 View deployment

anthonyshew approved these changes Jan 9, 2026

View reviewed changes

vercel Bot deployed to Preview January 9, 2026 20:02 View deployment

vercel Bot deployed to Preview January 9, 2026 20:11 View deployment

vercel Bot reviewed Jan 9, 2026

View reviewed changes

Comment thread packages/cli/tsconfig.json

jeffsee55 reviewed Jan 9, 2026

View reviewed changes

Comment thread packages/cli/scripts/build.mjs

mehulkar approved these changes Jan 10, 2026

View reviewed changes

Comment thread .changeset/cli-esm-migration.md

Comment thread packages/cli/scripts/start.js

tknickman force-pushed the tknickman/cli-esm-migration branch from a08d407 to 4384a91 Compare January 12, 2026 14:56

vercel Bot deployed to Preview January 12, 2026 14:57 View deployment

vercel Bot deployed to Preview January 12, 2026 18:14 View deployment

tknickman and others added 13 commits January 12, 2026 13:23

fix: convert scripts/start.js to ESM

a439110

The start.js script used require() which fails with "type": "module". Convert to dynamic import() to fix test failures. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: handle ESM file:// URLs in getPackageJSON

77f0050

In ESM, callSite.getFileName() returns a file:// URL instead of a regular file path. This caused path.join to malform the path and the package.json lookup to fail. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

chore: add changeset for ESM migration

689ab79

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: await dynamic import in start.js

b9a719d

Without await, the script could exit before the imported module finishes executing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: remove internal package from changeset

88c75f9

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

[cli] Fix file-url tests for Windows compatibility

abba8bd

Use platform-specific paths instead of hardcoded Unix paths. fileURLToPath behaves differently on Windows (adds drive letter). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

[cli] Update tsconfig to support import.meta in tests

27a0bf8

Set module to es2022 to enable import.meta support for ESM unit tests while maintaining compatibility with existing code that doesnt use explicit file extensions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

[cli] Clarify comment in compile-templates.mjs

4ee953e

Explain why we rename to .cjs (ESM package needs explicit CJS extension) and why we delete instead of rename back (generating TypeScript instead). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

tknickman force-pushed the tknickman/cli-esm-migration branch from 1a74cfb to 4ee953e Compare January 12, 2026 18:24

vercel Bot deployed to Preview January 12, 2026 18:25 View deployment

tknickman enabled auto-merge (squash) January 12, 2026 18:39

[cli] Use dynamic import instead of require in compile-templates

0e900c9

Replace createRequire/require() with await import() which works with both ESM and CJS modules natively, simplifying the code. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel Bot deployed to Preview January 12, 2026 19:01 View deployment

styfle reviewed Jan 12, 2026

View reviewed changes

Comment thread packages/cli/scripts/compile-templates.mjs

styfle reviewed Jan 12, 2026

View reviewed changes

Comment thread packages/cli/src/vc.js Outdated

Update packages/cli/src/vc.js

50c773f

Co-authored-by: Steven <steven@ceriously.com>

vercel Bot deployed to Preview January 12, 2026 19:18 View deployment

styfle reviewed Jan 12, 2026

View reviewed changes

Comment thread packages/cli/test/fixtures/unit/monorepo-link/.gitignore

styfle reviewed Jan 12, 2026

View reviewed changes

Comment thread packages/cli/tsconfig.json

styfle approved these changes Jan 12, 2026

View reviewed changes

tknickman merged commit e959b59 into main Jan 12, 2026
346 of 348 checks passed

tknickman deleted the tknickman/cli-esm-migration branch January 12, 2026 19:56

vercel-release-bot mentioned this pull request Jan 12, 2026

Version Packages #14587

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[cli] Migrate build output from CommonJS to ESM#14566

[cli] Migrate build output from CommonJS to ESM#14566
tknickman merged 15 commits intomainfrom
tknickman/cli-esm-migration

tknickman commented Jan 9, 2026

Uh oh!

changeset-bot Bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

TooTallNate commented Jan 9, 2026

Uh oh!

Uh oh!

Uh oh!

mehulkar left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jan 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

tknickman commented Jan 9, 2026

Summary

Key Changes

Why ESM?

Backwards Compatibility

Test plan

Uh oh!

changeset-bot Bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 Test Strategy

Results

Uh oh!

Uh oh!

TooTallNate commented Jan 9, 2026

Uh oh!

Uh oh!

Uh oh!

mehulkar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 CLI Tarball Ready

Quick Test

Use in vercel.json

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

changeset-bot Bot commented Jan 9, 2026 •

edited

Loading

github-actions Bot commented Jan 9, 2026 •

edited

Loading

github-actions Bot commented Jan 12, 2026 •

edited

Loading