browser based ui for metalsmith debugging
JavaScript HTML CSS
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


npm github-issues stars forks

Browser based debug interface for metalsmith

Provides nice ui to navigate metalsmith files and metadata, allowing you to view any stage of the build process


  • nice ui for exploring files & metadata
  • can jump forwards and backwards through the build process
  • cool react based client

files interface

See the annotated source or github repo


npm i --save metalsmith-debug-ui


metalsmith-debug-ui clones your metalsmith files and metadata strutures at different times during the build process and stores this history. Then it injects a browser based client into your build output which allows you to view that history.

patch mode

This will report after every plugin. You need to patch your metalsmith instance.

import Metalsmith from 'metalsmith'
import { patch } from 'metalsmith-debug-ui'

let ms = Metalsmith('src')



report mode

Just call report as a plugin

import Metalsmith from 'metalsmith'
import { report } from 'metalsmith-debug-ui'

let ms = Metalsmith('src') // no need to patch

.use(report('stage 1'))
.use(report('stage 2'))

viewing output

The client should be built with the rest of your site, and will be located at debug-ui/index.html in your build directory. You should use your favourite static development server to view it in the same way you would view anything else in your build directory.

errors during build

When a plugin throws an error metalsmith will just die as per normal behaviour, but the data debug-ui has collected will still be written to the build dir.

The only problem is that if you're using a dev server like metalsmith-dev-server you won't be able to view the ui to see what went wrong. I recommend implementing browser-sync or something instead.

anonymous plugins

It's difficult to reliably detect the names of plugins in order to report them in the ui. debug-ui first tries to sniff the plugin name from a stack trace, if that fails it checks whether the plugin returns a named function, and if that fails it will simply list the plugin as anonymous.

In most cases this is satisfactory. If something is reported as anonymous you can easily work out what it is by looking at the plugins before and after it.


see metalsmith-all-the-things for a full working demo.



plugin compatibility

logging Some plugins may not write to the debug-ui log, although I haven't found any yet. In theory any plugins using debug v2.x.x should work. If you find one please post an issue.

managed ms build fn some plugins wrap the build fn so they can run it any time the fs changes (like metalsmith-watch, metalsmith-browser-sync, et cetera). You're better off doing this with npm scripts, but if you must use these plugins then you'll need to clear debug-ui's data each time the build starts with a call to the clear function, something like this:

import { clear } from 'metalsmith-debug-ui'

.use(() => debugUi.clear())
// ...




Deprecation warning re: parseQuery is from upstream package. Don't worry about it.

npm run watch


Levi Wheatcroft


Contributions welcome; Please submit all pull requests against the master branch.