Switch to ESM by kibertoad · Pull Request #2138 · handlebars-lang/handlebars.js

kibertoad · 2026-03-19T22:10:23Z

Drop support for legacy formats like CJS/AMD/UMD
Convert everything relevant to ESM (grunt part will be dropped together with another PR)

kibertoad · 2026-03-19T22:25:29Z

we need to convert parser package first (handlebars-lang/handlebars-parser#30)

jaylinski · 2026-03-20T20:22:19Z

we need to convert parser package first (handlebars-lang/handlebars-parser#30)

Hm... it already exports modules as ESM, why doesn't this work?

…nto feat/switch-to-esm # Conflicts: # Gruntfile.cjs # tasks/publish-to-aws.js # tasks/util/grunt-async-task.cjs # tasks/version.cjs

kibertoad · 2026-03-22T13:59:01Z

@@ -1,12 +0,0 @@
-import Handlebars from 'handlebars/runtime';
-import hbs from 'handlebars-inline-precompile';
-import { assertEquals } from '../../webpack-test/src/lib/assert';


this is a niche pattern that seems to be already dead, https://www.npmjs.com/package/@roundingwellos/babel-plugin-handlebars-inline-precompile has only 80 weekly downloads (and it doesn't work with ESM)

kibertoad · 2026-03-22T14:12:16Z

@jaylinski finally ready for the review!

Copilot

Pull request overview

This PR completes a broad ESM migration across the package (including build/test tooling), while removing legacy CJS/AMD/UMD-related assets and expectations.

Changes:

Switch the published package to ESM (type: "module") and define explicit exports for main + runtime entrypoints.
Convert build/test configs and task scripts to ESM; remove AMD/CJS/UMD integration paths and fixtures.
Introduce a conditional #source-node implementation to keep source-map support workable across Node vs browser bundling.

Reviewed changes

Copilot reviewed 76 out of 85 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
vitest.config.js	Updates coverage paths/thresholds for ESM/lib output.
types/tsconfig.json	Switches TS module settings to ESM + bundler resolution.
types/index.d.ts	Updates runtime module typing away from `export =`.
tests/rspack/rspack.test.js	Updates rspack output tests for ESM + removed legacy formats.
tests/integration/webpack-test/src/handlebars-esm-import-test.js	Imports from package root (`handlebars`) instead of deep path.
tests/integration/webpack-babel-test/webpack.config.js	Removes obsolete webpack+babel integration test config.
tests/integration/webpack-babel-test/test.sh	Removes obsolete integration runner.
tests/integration/webpack-babel-test/src/lib/assert.js	Removes obsolete helper.
tests/integration/webpack-babel-test/src/handlebars-inline-precompile-test.js	Removes obsolete integration test case.
tests/integration/webpack-babel-test/package.json	Removes obsolete integration package.
tests/integration/webpack-babel-test/.gitignore	Removes obsolete integration ignores.
tests/integration/webpack-babel-test/.babelrc	Removes obsolete babel config.
tests/integration/rollup-test/src/index.js	Updates rollup integration to import from package root.
tests/integration/rollup-test/package.json	Marks rollup integration package as ESM (`type: module`).
tests/integration/multi-nodejs-test/run-handlebars.js	Converts multi-node test script to ESM imports.
tests/integration/multi-nodejs-test/package.json	Marks multi-node integration as ESM (`type: module`).
tests/browser/tests/lib.spec.js	Converts Playwright test file to ESM and drops UMD smoke pages.
tests/browser/playwright.config.js	Converts Playwright config to ESM export default.
tests/bench/templates.js	Adds benchmark template corpus in `.js` (ESM) form.
tests/bench/size.js	Switches bench imports from `.mjs` to `.js`.
tests/bench/report.js	Adds bench reporting utilities in `.js` (ESM).
tests/bench/perf.js	Switches bench imports from `.mjs` to `.js`.
tests/bench/compare.js	Switches compare imports/help text from `.mjs` to `.js`.
tasks/version.js	Converts version task to ESM + exports helper.
tasks/util/git.js	Converts git util to ESM named exports.
tasks/util/exec-file.js	Removes unused exec wrapper module.
tasks/tests/publish-to-aws.test.js	Converts task tests to ESM imports.
tasks/tests/git.test.js	Converts git util tests to ESM imports.
tasks/tests/fake-s3.js	Converts fake S3 server helper to ESM export.
tasks/tests/cli.test.js	Converts CLI tests to ESM + updates CLI filename/options.
tasks/publish-to-aws.js	Converts publish script to ESM + adds “run as script” guard.
spec/vendor/require.js	Removes vendored RequireJS (AMD no longer supported).
spec/umd.html	Removes UMD smoke test page.
spec/umd-runtime.html	Removes UMD runtime smoke test page.
spec/tokenizer.js	Removes tokenizer spec file (legacy test coverage).
spec/spec.js	Converts mustache-spec loader to ESM-safe JSON reading.
spec/source-map.js	Simplifies source-map loading logic (now ESM context).
spec/require.js	Removes require.extensions-based tests.
spec/precompiler.js	Converts precompiler specs to import ESM lib sources.
spec/expected/source.map.amd.js	Removes AMD expected artifact.
spec/expected/partial.template.js	Removes AMD expected artifact.
spec/expected/non.empty.amd.known.helper.js	Removes AMD expected artifact.
spec/expected/non.default.extension.amd.js	Removes AMD expected artifact.
spec/expected/namespace.amd.js	Removes AMD expected artifact.
spec/expected/help.menu.txt	Updates CLI help expectations for new flags/filename.
spec/expected/handlebar.path.amd.js	Removes AMD expected artifact.
spec/expected/empty.root.amd.js	Removes AMD expected artifact.
spec/expected/empty.namespace.js	Updates expected namespace output for non-AMD wrapper.
spec/expected/empty.name.amd.js	Removes AMD expected artifact.
spec/expected/empty.amd.simple.js	Removes AMD expected artifact.
spec/expected/empty.amd.namespace.js	Removes AMD expected artifact.
spec/expected/empty.amd.min.js	Removes AMD expected artifact.
spec/expected/empty.amd.js	Removes AMD expected artifact.
spec/expected/bom.amd.js	Removes AMD expected artifact.
spec/env/node.js	Converts node spec env bootstrap to ESM imports.
spec/env/browser.js	Converts browser spec env bootstrap to ESM + createRequire.
runtime.js	Switches runtime alias to ESM re-export from `lib/`.
runtime.d.ts	Updates runtime typings to default-import style.
rspack.config.js	Converts bundler config to ESM + changes output library type to `self`.
package.json	Enables ESM (`type: module`), adds `exports`/`imports`, removes SWC CJS build, updates scripts.
lib/precompiler.js	Converts precompiler implementation to ESM exports + removes AMD/CJS wrappers + async minify import.
lib/index.js	Makes ESM entrypoint and adds many named exports for CJS interop.
lib/handlebars/runtime.js	Updates internal imports to include `.js` extensions.
lib/handlebars/logger.js	Updates internal imports to include `.js` extensions.
lib/handlebars/internal/proto-access.js	Updates internal imports to include `.js` extensions.
lib/handlebars/helpers/with.js	Updates internal imports to include `.js` extensions.
lib/handlebars/helpers/if.js	Updates internal imports to include `.js` extensions.
lib/handlebars/helpers/each.js	Updates internal imports to include `.js` extensions.
lib/handlebars/helpers/block-helper-missing.js	Updates internal imports to include `.js` extensions.
lib/handlebars/helpers.js	Updates internal imports to include `.js` extensions.
lib/handlebars/decorators/inline.js	Updates internal imports to include `.js` extensions.
lib/handlebars/decorators.js	Updates internal imports to include `.js` extensions.
lib/handlebars/compiler/source-node.node.js	Adds Node `SourceNode` entry using `source-map`.
lib/handlebars/compiler/source-node.browser.js	Adds browser stub `SourceNode` implementation.
lib/handlebars/compiler/javascript-compiler.js	Updates internal imports to include `.js` extensions.
lib/handlebars/compiler/compiler.js	Updates internal imports to include `.js` extensions.
lib/handlebars/compiler/code-gen.js	Switches SourceNode resolution to `#source-node`.
lib/handlebars/base.js	Updates internal imports to include `.js` extensions.
lib/handlebars.runtime.js	Adds named re-exports for runtime CJS interop.
lib/handlebars.js	Converts primary entry to ESM + updates import extensions.
eslint.config.js	Adds compat lint config targeting `lib/**`.
.swcrc	Removes SWC config used for CJS builds.
.oxlintrc.json	Updates bench file glob from `.mjs` to `.js`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

kibertoad · 2026-03-22T20:44:13Z

@jaylinski all review comments addressed

kibertoad · 2026-03-25T19:35:57Z

@jaylinski is anything left on this one?

jaylinski · 2026-03-25T19:42:26Z

@jaylinski is anything left on this one?

I still want to give this a thorough (manual) test. Planned for tomorrow. Sorry for the wait.

jaylinski

Awesome! 💯

(Please fix merge conflicts and merge.)

jaylinski · 2026-03-29T20:14:58Z

+    "#source-node": {
+      "node": "./lib/handlebars/compiler/source-node.node.js",
+      "default": "./lib/handlebars/compiler/source-node.browser.js"
+    }


Nice hack. Didn't know you can do this.

kibertoad added 4 commits March 20, 2026 00:09

Switch to ESM

ef19271

Restore coverage

4bf3983

Cleanup

c659867

Fixes

d62ad5c

kibertoad marked this pull request as draft March 19, 2026 22:25

kibertoad added 7 commits March 21, 2026 13:19

Merge branch 'master' of https://github.com/kibertoad/handlebars.js i…

6e54405

…nto feat/switch-to-esm # Conflicts: # Gruntfile.cjs # tasks/publish-to-aws.js # tasks/util/grunt-async-task.cjs # tasks/version.cjs

resolve conflicts

411f05f

fix CI

88db636

update parser for ESM support

d319ea3

remove test that tested parser internals

a32ff01

fix typecheck

165539a

remove obsolete pattern

7e22795

kibertoad commented Mar 22, 2026

View reviewed changes

CJS interop

a4e33c7

kibertoad marked this pull request as ready for review March 22, 2026 14:12

jaylinski requested a review from Copilot March 22, 2026 19:58

Copilot started reviewing on behalf of jaylinski March 22, 2026 19:59 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

Comment thread spec/precompiler.js

Comment thread tests/rspack/rspack.test.js

Comment thread tests/rspack/rspack.test.js

Comment thread spec/source-map.js

Comment thread tasks/version.js Outdated

Comment thread lib/index.js

kibertoad added 2 commits March 22, 2026 22:42

address review comments

b6202e2

fix review comment

01d59ca

mohd-akram mentioned this pull request Mar 26, 2026

Simplify helper wrapper #2041

Open

jaylinski mentioned this pull request Mar 26, 2026

Publish ESM Version #2080

Closed

jaylinski approved these changes Mar 29, 2026

View reviewed changes

Conversation

kibertoad commented Mar 19, 2026

Uh oh!

kibertoad commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jaylinski commented Mar 20, 2026

Uh oh!

kibertoad Mar 22, 2026

Choose a reason for hiding this comment

Uh oh!

kibertoad commented Mar 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kibertoad commented Mar 22, 2026

Uh oh!

kibertoad commented Mar 25, 2026

Uh oh!

jaylinski commented Mar 25, 2026

Uh oh!

jaylinski left a comment

Choose a reason for hiding this comment

Uh oh!

jaylinski Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kibertoad commented Mar 19, 2026 •

edited

Loading