Feature: provide metalsmith.on('built')

Author: webketjeCreated Aug 31, 2023Updated Sep 5, 2023
Labelsstage:drafttype:feature

Currently only the end-user of a metalsmith build can choose to do post-processing on the build.

Use cases:

  • Plugins like metalsmith-debug-ui add dynamically generated files to the build that are not intended for plugin processing. Providing such an event would allow them to do this safely without requiring user tweaks with pattern-matching in subsequent plugins
  • This event would also allow plugins to encapsulate command-line tools (like exiftool or 7zip) to run on metalsmith.destination() with the guarantee that files have already been written

Given that plugins have access to the files object and it is passed by reference, care should be taken in the docs to discourage altering or overwriting user files in these event listeners (or Object.freez'ing it?). The listeners should be executed sequentially, and should properly handle async (maybe use another Ware instance?)

Sample usage:

javascript
// adding a dynamically generated file not intended for processing
metalsmith.use((files, metalsmith, done) => {
  metalsmith.on('built', async files => {
    const file = { contents: await fsPromises.readFile('dynamically-generated.html', 'utf-8') }
    files['dynamically-generated.html']  = file
  })
})

// running a command after completion
metalsmith.use((files, metalsmith, done) => {
  metalsmith.on('built', () => {
    execSync('ls -la', { cwd: metalsmith.destination() })
  })
})