Uh oh!
There was an error while loading. Please reload this page.
Migrate Core output from CJS to ESM - #2863
Merged
Merged
Conversation
Core uses `require` imports due to CJS.
ESM uses `import { } and export { }` syntax
instead.
Change all import/export formats to use
ESM-compatible syntax.See MarkBind#2836 or commit #265fbac for the reasons why.
Dynamic imports are used throughout core code. These imports (with `require()`) are not compatible with ESM syntax. Replace with `createRequire` where necessary. Additionally, use fileURLToPath for __dirname alternative in ESM.
Importing ignore uses a fragile workaround. Change to importing using createRequire() This allows the CJS module to be imported as expected in the ESM environment.
src files use `__filename` variable name with `import.meta.url`. This causes an issue with transpiling `import.meta` calls to CJS - see: javiertury/babel-plugin-transform-import-meta#8 Change `__filename` to `__filepath`
core-web/ uses CJS `export = ` format.
This doesn't work with ES modules.
Change to `export { ... }` format.Let's * Update package.json to specify `type: module` * Update tsconfig to specify module resolution * Update tsconfig lint
Jest doesn't support ESM testing OOB. Use babel to transpile to CJS, allowing testing. See MarkBind#2836 or #5d66aac for more discussion.
Add eslintrc.cjs file to core. Use same rules as cli, with some changes.
NodeNext imposes stricter type-checking. Let's add module declarations for: - markdown-it internal subpaths (lib/renderer, lib/token, etc.) - Untyped markdown-it plugins and fastmatter - csv-parse/lib/sync subpath (csv-parse v4) - @markbind/core-web UMD bundle Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Markdown-it-linkify was bumped to v4 from v3 during development of this branch. There may be breaking changes introduced by this. Undo bump and reset to version that was being used before. Bumping markdown-it should be done in its own PR as there may be other implications that should be observed.
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@## master #2863 +/- ##
==========================================
- Coverage 71.99% 70.29% -1.71%
==========================================
Files 132 129 -3 Lines 7352 6951 -401 Branches 1635 1633 -2 ==========================================
- Hits 5293 4886 -407 - Misses 1958 1964 +6
Partials 101 101 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR continues the repository-wide ESM migration (issue #2615) by converting the @markbind/core package output and its test environment to ES Modules, aligning Core with the earlier CLI ESM work.
Changes:
- Switch Core’s TS compilation to
NodeNextand setpackages/coreto"type": "module". - Update Core source + tests to ESM-style imports (including explicit
.jsfor internal relative imports) and adjust several CJS interop points. - Replace
ts-jestwith a Babel-based Jest setup for Core tests.
Reviewed changes
Copilot reviewed 134 out of 138 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| packages/core/tsconfig.lint.json | Lint TS config updated for NodeNext module resolution. |
| packages/core/tsconfig.json | Core TS compilation switched to NodeNext/NodeNext resolution. |
| packages/core/test/unit/utils/utils.ts | Update test imports to ESM-style paths. |
| packages/core/test/unit/utils/LockManager.test.ts | Update LockManager import to new ESM export shape. |
| packages/core/test/unit/utils/HtmlValidationUtil.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/plugins/default/tree.test.ts | Update default plugin imports for ESM paths/shape. |
| packages/core/test/unit/plugins/default/shorthandSyntax.test.ts | Update default plugin imports for ESM paths/shape. |
| packages/core/test/unit/plugins/default/plantuml.test.ts | Update plugin + NodeProcessor imports for ESM paths. |
| packages/core/test/unit/plugins/default/mermaid.test.ts | Update imports for ESM paths/shape. |
| packages/core/test/unit/plugins/default/dataTable.test.ts | Update imports for ESM paths/shape. |
| packages/core/test/unit/plugins/default/anchor.test.ts | Update imports for ESM paths/shape. |
| packages/core/test/unit/lib/progress/node-progress.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/nunjucks-extensions/set-external.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/nunjucks-extensions/nunjucks-date.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/plugins/markdown-it-radio-button.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/plugins/markdown-it-icons.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/plugins/markdown-it-footnotes.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/plugins/markdown-it-double-delimiter.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/plugins/markdown-it-colour-text.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/plugins/markdown-it-center-text.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/plugins/markdown-it-block-embed.test.ts | Update block-embed plugin import to new named export entrypoint. |
| packages/core/test/unit/lib/markdown-it/plugins/markdown-it-alt-frontmatter.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/index.test.ts | Update markdown-it import to explicit index entrypoint. |
| packages/core/test/unit/lib/markdown-it/highlight/helper.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/highlight/Highlighter.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/highlight/HighlightRuleComponent.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/lib/markdown-it/highlight/HighlightRule.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/html/linkProcessor.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/html/includePanelProcessor.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/html/cardStackProcessor.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/html/SiteLinkManager.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/html/NodeProcessor.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/Site/SitePagesManager.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/Site/SiteGenerationManager.test.ts | Update imports + require paths for ESM builds. |
| packages/core/test/unit/Site/SiteDeployManager.test.ts | Adjust mocks/imports for ESM module paths. |
| packages/core/test/unit/Site/SiteAssetsManager.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/Site/Site.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/Page/index.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/Page/filterIconAssets.test.ts | Update imports for ESM paths. |
| packages/core/test/unit/Page/PageVueServerRenderer.test.ts | Update dynamic imports for ESM paths. |
| packages/core/test/functional/Site.functional.test.ts | Update imports for ESM paths. |
| packages/core/src/variables/VariableRenderer.ts | Convert internal imports + patch load to ESM import. |
| packages/core/src/variables/VariableProcessor.ts | Convert internal imports to ESM paths. |
| packages/core/src/utils/logger.ts | Update type-only import path for ESM. |
| packages/core/src/utils/htmlValidationUtil.ts | Update internal logger import to ESM path. |
| packages/core/src/utils/LockManager.ts | Convert singleton export from export = to named ESM export. |
| packages/core/src/plugins/web3Form.ts | Convert plugin module from CJS export to ESM exports; update markdown-it import. |
| packages/core/src/plugins/mermaid.ts | Convert plugin module from CJS export to ESM exports. |
| packages/core/src/plugins/mathDelimiters.ts | Convert plugin module from CJS export to ESM exports; update texmath import. |
| packages/core/src/plugins/googleAnalytics.ts | Convert plugin module from CJS export to ESM exports. |
| packages/core/src/plugins/filterTags.ts | Convert plugin module from CJS export to ESM exports; update lodash usage. |
| packages/core/src/plugins/disqus.ts | Convert plugin module from CJS export to ESM exports; formatting cleanup. |
| packages/core/src/plugins/default/markbind-plugin-tree.ts | Convert plugin module from CJS export to ESM exports; update lodash/md usage. |
| packages/core/src/plugins/default/markbind-plugin-shorthandSyntax.ts | Convert plugin module from CJS export to ESM exports. |
| packages/core/src/plugins/default/markbind-plugin-plantuml.ts | Convert plugin module to ESM imports/exports; replace crypto require with ESM-friendly usage; add import.meta dirname. |
| packages/core/src/plugins/default/markbind-plugin-anchors.ts | Convert plugin module from CJS export to ESM exports. |
| packages/core/src/plugins/dataTable.ts | Convert plugin module from CJS export to ESM exports; update markdown-it import. |
| packages/core/src/plugins/codeBlockWrapButtons.ts | Update internal imports to ESM paths; convert to ESM exports. |
| packages/core/src/plugins/codeBlockCopyButtons.ts | Update internal imports to ESM paths; convert to ESM exports. |
| packages/core/src/plugins/codeBlockButtonsAssets/codeBlockButtonsContainer.ts | Update MbNode import to ESM path. |
| packages/core/src/plugins/algolia.ts | Convert plugin module from CJS export to ESM exports. |
| packages/core/src/plugins/PluginManager.ts | Update to ESM-style imports; replace patch require; adjust lodash usage; add import.meta dirname utilities. |
| packages/core/src/plugins/Plugin.ts | Update to ESM-style imports; replace patch require; introduce createRequire for loading plugins. |
| packages/core/src/patches/nunjucks/nunjucks-submodules.d.ts | Update nunjucks internal module declarations to .js deep imports. |
| packages/core/src/patches/nunjucks/nunjucks-internals.d.ts | Update nunjucks internal module declarations to .js deep imports; extend runtime Frame typing for patching. |
| packages/core/src/patches/nunjucks/load-event.ts | Update nunjucks runtime import to .js deep import; adjust lib access. |
| packages/core/src/patches/nunjucks/index.ts | Update patch imports to explicit .js paths. |
| packages/core/src/patches/nunjucks/context-overrides-frame.ts | Refactor patch to avoid require of frozen ESM namespace; update internal imports and compiler typing. |
| packages/core/src/patches/index.ts | Convert patch barrel export from export = to named ESM export. |
| packages/core/src/lib/progress/index.ts | Update re-export path to include .js. |
| packages/core/src/lib/nunjucks-extensions/set-external.ts | Update csv-parse/nunjucks deep imports for ESM; adjust parser import pattern. |
| packages/core/src/lib/nunjucks-extensions/index.ts | Update re-export paths to include .js. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-radio-button.ts | Update markdown-it deep import path and internal code cleanup. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-footnotes.ts | Update internal constants import to ESM path; add token typing in filter callback. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/services/YouTubeService.ts | Update relative import to .js path; normalize quotes. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/services/VineService.ts | Convert from CJS module.exports to ESM exports; minor refactors. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/services/VimeoService.ts | Update relative import to .js path; normalize quotes. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/services/VideoServiceBase.ts | Update relative import to .js path. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/services/SlideShareService.ts | Update relative import to .js path. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/services/PreziService.ts | Update relative import to .js path. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/services/PowerPointOnlineService.ts | Update relative import to .js path. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/index.ts | Convert default export to named export; update internal imports and minor cleanup. |
| packages/core/src/lib/markdown-it/plugins/markdown-it-block-embed/PluginEnvironment.ts | Update internal imports to .js; adjust VineService import/export shape; minor cleanup. |
| packages/core/src/lib/markdown-it/patches/markdown-it-emoji-fixed.ts | Convert to ESM export; switch to import attributes for JSON; normalize property access. |
| packages/core/src/lib/markdown-it/patches/custom-component/inlineTags.ts | Convert export = to named ESM export. |
| packages/core/src/lib/markdown-it/patches/custom-component/htmlInlineRule.ts | Update internal import to .js; convert export = to named ESM export; minor formatting. |
| packages/core/src/lib/markdown-it/patches/custom-component/htmlBlockRule.ts | Convert require-style imports to ESM; convert export = to named ESM export; formatting cleanup. |
| packages/core/src/lib/markdown-it/patches/custom-component/customComponentPlugin.ts | Convert require-style imports to ESM imports; update markdown-it import path. |
| packages/core/src/lib/markdown-it/index.ts | Convert markdown-it setup to ESM exports; replace runtime require(...) plugins with ESM imports; update emoji patch usage. |
| packages/core/src/lib/markdown-it/highlight/Highlighter.ts | Update relative import to include .js. |
| packages/core/src/lib/markdown-it/highlight/HighlightRuleComponent.ts | Update relative import to include .js. |
| packages/core/src/lib/markdown-it/highlight/HighlightRule.ts | Update relative import to include .js. |
| packages/core/src/html/warnings.ts | Update internal imports to ESM paths. |
| packages/core/src/html/vueSlotSyntaxProcessor.ts | Consolidate lodash imports; update node import path. |
| packages/core/src/html/siteAndPageNavProcessor.ts | Update internal imports to ESM paths; replace patch require with import. |
| packages/core/src/html/linkProcessor.ts | Switch lodash import; add createRequire interop for ignore CJS package; update internal imports to ESM paths. |
| packages/core/src/html/includePanelProcessor.ts | Consolidate lodash imports; convert internal imports to ESM paths; replace patch require with import. |
| packages/core/src/html/headerProcessor.ts | Consolidate lodash imports; update internal imports to ESM paths. |
| packages/core/src/html/elements.ts | Consolidate lodash imports; update internal imports to ESM paths. |
| packages/core/src/html/codeblockProcessor.ts | Consolidate lodash imports; update markdown-it import to ESM entrypoint. |
| packages/core/src/html/cardStackProcessor.ts | Update node import to ESM path. |
| packages/core/src/html/SiteLinkManager.ts | Consolidate lodash imports; update internal imports to ESM paths. |
| packages/core/src/html/NodeProcessor.ts | Convert internal imports to ESM paths; replace fastmatter require with ESM import; replace patch require with import. |
| packages/core/src/html/MdAttributeRenderer.ts | Consolidate lodash imports; update internal imports to ESM paths. |
| packages/core/src/html/MarkdownProcessor.ts | Update markdown-it import to ESM entrypoint. |
| packages/core/src/html/FootnoteProcessor.ts | Update internal imports to ESM paths. |
| packages/core/src/html/CustomListIconProcessor.ts | Update internal imports to ESM paths; switch emoji patch import to ESM export. |
| packages/core/src/html/Context.ts | Update CyclicReferenceError import to ESM path. |
| packages/core/src/errors/index.ts | Convert export = to named ESM export. |
| packages/core/src/errors/CyclicReferenceError.ts | Convert export = to named ESM export. |
| packages/core/src/declarations.d.ts | Add ambient module declarations for NodeNext/ESM type gaps. |
| packages/core/src/Site/template.ts | Update imports to ESM paths; add import.meta dirname utilities. |
| packages/core/src/Site/index.ts | Update imports to ESM paths; replace patch require with import. |
| packages/core/src/Site/constants.ts | Replace curated lodash-function object with full lodash _ export. |
| packages/core/src/Site/SitePagesManager.ts | Update imports to ESM paths; add import.meta dirname utilities. |
| packages/core/src/Site/SiteGenerationManager.ts | Update imports to ESM paths; add JSON import for version; add import.meta dirname utilities. |
| packages/core/src/Site/SiteDeployManager.ts | Update imports to ESM paths; adjust simple-git import style for ESM. |
| packages/core/src/Site/SiteConfig.ts | Update FrontMatter import to ESM path. |
| packages/core/src/Site/SiteAssetsManager.ts | Add createRequire interop for ignore CJS package; update internal imports. |
| packages/core/src/Page/index.ts | Consolidate lodash; add JSON import for version; add LockManager ESM import; adjust js-beautify interop; replace patch require with import. |
| packages/core/src/Page/PageVueServerRenderer.ts | Switch core-web bundle import wiring; update internal imports to ESM paths. |
| packages/core/src/Page/PageSources.ts | Consolidate lodash import. |
| packages/core/src/Page/PageConfig.ts | Update internal imports to ESM paths. |
| packages/core/src/Layout/index.ts | Update internal imports to .js paths. |
| packages/core/src/Layout/LayoutManager.ts | Update internal imports to ESM paths. |
| packages/core/src/Layout/Layout.ts | Update internal imports to ESM paths. |
| packages/core/src/External/ExternalManager.ts | Consolidate lodash import; update internal imports to ESM paths. |
| packages/core/src/External/External.ts | Update imports to ESM paths; adjust js-beautify interop. |
| packages/core/package.json | Mark package as ESM; add Babel/Jest deps for new test pipeline. |
| packages/core/jest.config.js | Remove old ts-jest config. |
| packages/core/jest.config.cjs | Add new Jest config for Babel-based TS transpilation. |
| packages/core/index.ts | Update exports to ESM index entrypoints. |
| packages/core/babel.config.cjs | Add Babel config for Jest TS transpilation (ESM→CJS). |
| packages/core/.eslintrc.cjs | Add Core-scoped ESLint overrides for ESM import extensions + lodash rules. |
| packages/core-web/src/index.js | Update VueCommonAppFactory import to named exports. |
| packages/core-web/src/VueCommonAppFactory.js | Change export from default object to named exports. |
| packages/cli/src/lib/live-server/index.js | Update @markbind/core fsUtil import for ESM export shape. |
| package-lock.json | Lockfile updates reflecting dependency/tooling changes for Babel/Jest/ESM. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Changes converted default export syntax for vueCommonAppFactory to non-default. This caused a regression in the CI environment when build:web was used. Revert the change and maintain old import/export style for core-web.
Harjun751
marked this pull request as ready for review
March 21, 2026 08:00
yihao03
reviewed
Mar 21, 2026
yihao03
left a comment
Contributor
There was a problem hiding this comment.
After looking at quite a few files I noticed its mostly just changes in import/export syntax, and sometimes some linting? LGTM overall but just wonders if we should be using default exports/imports in some cases
Uh oh!
There was an error while loading. Please reload this page.
gerteck
approved these changes
Mar 22, 2026
Member
There was a problem hiding this comment.
Thank you for your PR @Harjun751
LGTM
Seeing a lot of lint fixes in the PR.
Migrated from
import XXX from '..'to import XXX from '...js' because ESM under NodeNext requires explicit file extensions in relative imports since Node.js no longer auto-resolves extensions like CJS did.Migrated from optimized lodash imports (e.g. import has from 'lodash/has') to full lodash imports (e.g. import _ from 'lodash') because TypeScript's NodeNext module resolution cannot resolve types from lodash's per-function subpath imports in ESM, with the tradeoff of increased node_modules size being acceptable since lodash is only used in the CLI and does not affect end-user bundle size.
Migration added
import { createRequire } from 'module'; const require = createRequire(import.meta.url);as ESM modules do not haverequireavailable natively, socreateRequire(import.meta.url)creates a CJS-style require function rooted at the current file's location, needed to load CJS packages that can't be properly imported via ESM's import syntax.Additionally, ESM has no
__dirnameor__filenameglobals like CJS does, so they have to be manually reconstructed from import.meta.url.declarations.d.tsfile added because the ESM/NodeNext migration introduced stricter module resolution, causing TypeScript to fail to resolve types for packages that lack a proper exports field in their package.json (e.g. markdown-it v12, csv-parse v4) or have no type definitions at all (e.g. markdown-it-mark, fastmatter). This file acts as a compatibility shim, manually declaring the types for these packages so the codebase compiles cleanly under NodeNext without waiting for every dependency to add ESM support.Migrated from
ts-jestto Babel for Jest test transformation because ts-jest compiles TypeScript to ESM output which Jest's CJS environment cannot run, whereas Babel transforms the source on the fly while converting ESM to CJS via modules: 'cjs', allowing Jest to run the tests without a separate build step.Also noted migrated of plugins from export assignment (
export = { ... }) which exported a single CJS object, to named exports (export { ... }) which is the proper ESM way of exporting multiple values individually.
Member
There was a problem hiding this comment.
At some point in the future, to complete the ESM migration entirely, PluginManager.ts which still relies on CJS interop workarounds (createRequire, __dirname reconstruction, require.resolve) to not use these workarounds.
These are currently used as some plugin files themselves may not have been fully migrated to ESM yet. These workarounds act as a bridge allowing the now-ESM PluginManager to dynamically load plugins that are still CJS.
This is also a user-facing change that would require a deprecation notice to be communicated to users who have authored their own plugins in _markbind/plugins/, giving them time to migrate their plugins to ESM named exports before support for CJS plugins is dropped.
ContributorAuthor
There was a problem hiding this comment.
Just to clarify, the __dirname reconstruction is something we can't workaround - using import.meta.url is the "proper" way of doing so.
(see: MDN import.meta, StackOverflow: Alternative for __dirname in Node.js when using ES6 modules)
For the other require calls, I've created an issue (#2867 ) to investigate and handle the plugin issue.
Uh oh!
There was an error while loading. Please reload this page.
@Harjun751 Each PR must have a SEMVER impact label, please remember to label the PR properly. |
gerteck
commented
Mar 23, 2026
Member
tbh i don't know if this is really considered a patch or major version change, technically @markbind/core is not depended externally... hmm |
This was referenced Mar 23, 2026
Merged
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is the purpose of this pull request?
Works towards #2615
Overview of changes:
Mostly similar to #2836, though there are nitty-gritty differences
Anything you'd like to highlight/discuss:
Tests in core use babel now, meaning that the ESM test code is transpiled to CJS. This is just like CLI now.
Luckily, unlike the CLI ESM migration, no package was outright not working. And thankfully, with the winston migration done, I didn't get an issue with that!
Testing instructions:
Check that core-web builds is fine and not affected, since a component in that was slightly changed to conform with ESM syntax.
^ I would like to do this just as a sanity check because I think implications are quite wide with this PR. I'll get to it soon before merging.
Proposed commit message: (wrap lines at 72 characters)
Migrate Core package from CommonJS to ES Modules
type: 'module'Checklist: ☑️
Reviewer checklist:
Indicate the SEMVER impact of the PR:
At the end of the review, please label the PR with the appropriate label:
r.Major,r.Minor,r.Patch.Breaking change release note preparation (if applicable):