Metalsmith 2.5 Roadmap

[webketje]

This issue is meant to group & provide an overview of what features will be in release 2.5

• Basic ESM support, see this article
• Replace unyield with promise-based  #362
• Testing & optimizations for Windows Windows testing: attrib +h (hidden files), mklink (symlink equivalent?), file.mode #360
• Add metalsmith.debug/log method #259
• Provide metalsmith.env (env setting method) #354
• Rework metalsmith.metadata setter to always refer to the same object, see Side effects when setting global metadata #247
• Drop support for Node < 12 (cfr. adapt package.json engines.node)
• Resolve incosistency in directory option in JS vs CLI usage #355

[webketje]

Regarding ESM support:
Tested on a local branch, and the conclusion is that metalsmith and its core plugins already support ESM because they only use a default export. NodeJS "automagically" assigns module.exports to export default when running in ESM mode.

There are some traps that are useful to note for future developments:

• ES modules have no native loader for importing *.json files, so doing something like require('../package.json').version will make a CJS module incompatible with ES modules, unless a createRequire is done. No .json's will be required internally, so this is ok
• Named exports are not supported. If for example static methods are added to Metalsmith they cannot be imported as import { staticMethod } from 'metalsmith', only by destructuring the default export. No static methods will be added for 2.x, so this is ok. Even if they are added, the benefits of named imports are small (because Metalsmith is small and named exports would have a negligible impact for those of us using bundling)

Tests using a linked metalsmith package on diffferent Node versions with NVM resulted in inconvenient results for either the user or the maintainer:

• specifying a package.json exports property is a semver-major breaking change (for v3.x)
• specifying a shallow index.mjs wrapper and declaring"type": "commonjs" was inconvenient for ESM users as you needed to import from 'metalsmith/index.mjs
• declaring "type": "module" would be a lie
• unit testing with mocha was more of a pain

In conclusion, I will replace the wording "ESM support" to "Basic ESM support", and hold off major changes for 3.x