Plan ESM migration for Azure Functions Node.js Worker

[TsuyoshiUshio]

Summary

The Node.js ecosystem is steadily moving toward ES Modules (ESM) as the default module system. Several key dependencies of the Azure Functions Node.js Worker have already shipped ESM-only major versions, and Node.js itself is on a path to make ESM the default. The Worker currently uses CommonJS throughout, which will become increasingly difficult to maintain.

Ecosystem Facts

Node.js: ESM as default is in progress

• Node.js TSC discussed making --default-type=module the default (When to make --default-type=module the Node.js default nodejs/TSC#1445)
• Node.js 22.7.0+ can auto-detect module format (require() of ESM modules)
• Node.js 26.0.0 (released May 2026) removed --experimental-default-type and --experimental-transform-types, continuing the trend toward ESM-first
• PR to mark CommonJS as legacy in Node.js docs: doc: mark commonjs as legacy nodejs/node#57460
• npm CLI issue to default npm init --type=module: The --init-type flag should default to module npm/cli#8159
• Node.js continues to support CommonJS but is shifting it to opt-in rather than opt-out

Key npm packages going ESM-only

Several packages in the Worker's dependency chain have shipped ESM-only versions:

• long@5 (ESM-only): Required by @grpc/proto-loader >= 0.7.9 and protobufjs >= 8.0
• chalk@5, ora@6, globby@13, got@13, node-fetch@3, execa@6: Popular utilities that dropped CommonJS in major versions
• sindresorhus ecosystem: One of the largest package authors, ESM-only since 2021

protobufjs 8.x: ESM migration pressure on gRPC stack

protobufjs 8.0 depends on long@5 (ESM-only). This blocks upgrading:

• @grpc/proto-loader >= 0.7.9 requires long@5
• @grpc/proto-loader@0.8.0 requires protobufjs ^7.5.3 (still v7, but long@5)
• The Worker's proto generation script uses pbjs -w commonjs, which would need to change to -w es6

Current Worker State

• Worker entry point (nodejsWorker.js) uses require()
• Proto generation uses pbjs -w commonjs output format
• webpack bundles everything into CommonJS (libraryTarget: 'commonjs2')
• All source files use CommonJS require()/module.exports
• @grpc/grpc-js@1.8.22 and @grpc/proto-loader@0.7.8 are pinned to avoid long@5

Impact on Azure Functions Users

When the Worker migrates to ESM internally, user-facing behavior should remain compatible. However:

• Users writing ESM function apps (type: module in package.json) are already supported
• Users should be informed about the direction of the ecosystem
• Documentation should be updated to recommend ESM for new projects
• The v4 programming model already encourages ESM patterns

Proposed Phased Approach

Phase 1: Internal ESM readiness (no user impact)

• Migrate Worker source from CommonJS to ESM (TypeScript with ESM output)
• Update webpack config or switch to ESM-compatible bundler
• Update proto generation to -w es6
• Bump @grpc/proto-loader and @grpc/grpc-js to latest

Phase 2: Dependency unblocking

• Upgrade protobufjs to 8.x + protobufjs-cli 2.x
• Upgrade long to v5
• Unpin gRPC stack dependencies

Phase 3: User communication

• Update docs to recommend ESM for new projects
• Provide migration guide for CommonJS -> ESM function apps
• Announce timeline for any breaking changes

Related Issues and PRs

• Add ESM support for @azure/functions-core virtual module #791 - Add ESM support for @azure/functions-core virtual module (open PR)
• Bump protobufjs to ^7.5.5 and fix proto generation compatibility #804 - protobufjs bump blocked protobufjs 8.x due to ESM-only long@5 (merged)
• Critical: protobufjs < 7.5.5 arbitrary code execution vulnerability #803 - protobufjs vulnerability fix (closed)
• Add support for ES Modules #344 - Add support for ES Modules (closed)
• Respect package.json type: module for ESM Functions #531 - Respect package.json type: module for ESM Functions (closed)
• Add ES6 Style Exports #104 - Add ES6 Style Exports (open, 2018)
• When to make --default-type=module the Node.js default nodejs/TSC#1445 - When to make --default-type=module the Node.js default
• doc: mark commonjs as legacy nodejs/node#57460 - Mark CommonJS as legacy in docs