Goals for Metalsmith v3 (WIP)

metalsmith3-design-goals.md

Metalsmith v3 Goals

“Big Picture” Goals

• Modern ES code. ES/JS moves fast these days. I want Metalsmith 3 to be best-in-class, and stay best-in-class for several years.

• Performance (with Scalability). If Metalsmith 3 can boast performance that is so good, big companies with big websites start using it, that would be pretty fantastic. :)

• Convenience. Metalsmith is simple to use. It should remain so.

  When the plugin stack starts to grow, however, it’s not always simple to use. I’ve gotten much better at figuring out where an error happened when a build breaks, but only after a lot of frustration.

  I think we can do better. Whatever we can do to make a failed build as easy to troubleshoot as possible improves life for everyone.

• Better tooling. I’d like to set up a number of small supporting projects to help users and plugin authors. For example, some ESLint plugins/rules.

  I recently watched this video about a tool called JSCodeshift. It’s really, really impressive. I think it could be used to write a migration script for Metalsmith 2 users. It’s so powerful I suspect it can probably be useful in numerous ways after users migrate to Metalsmith 3.

Architectural Goals

As small as Metalsmith is, I’d like to see the next version broken into a small number of modules.

Here’s why.

• Core Library Customization. Metalsmith users should get 99.9999999% of their customization accomplished via plugins. (That’s nine 9s.)

  However, I want to add a few flexible places to Metalsmith’s core that allow customization of a few things that are difficult/impossible to accomplish via plugins alone.

  I’m not yet sure how to go about this, but I’m hoping to find a way to use this to improve the following areas:

  • Logging
  • Debugging (plugins can improve debugging, but I’d like some minimal-but-useful support for debugging in Metalsmith’s core)
  • Statistics (benchmarking/performance, metrics, etc.)

  Users must opt-in to enable these. They should all default to “off”.

• Loose coupling. Metalsmith is pretty good as-is on this point. I’d like to take it even further.

  I’ve been experimenting with refactoring Metalsmith into 2 components:

  • a module that manages configuration (metalsmith.{source,concurrency,clean,…}, etc.), and
  • a module that manages operations ({read,write,run,build,…}, etc.)

  Definite benefits: easier/better test coverage; maintainability. Possible benefits: core customization (mentioned above); performance.

  Apart from this, we can improve loose coupling by:

  • Factoring out the CLI as a separate package
  • Removing frontmatter (it should be a plugin!)

• « … » ( more stuff )