metalsmith-debug-ui

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

Features:

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

See the annotated source or github repo

install

npm i --save metalsmith-debug-ui

usage

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')

patch(ms)

ms
.use(...)
.build(...)

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

ms
.use(myFirstPlugin({...}))
.use(mySecondPlugin({...}))
.use(report('stage 1'))
.use(myFirstPlugin({...}))
.use(report('stage 2'))
.build(...)

metalsmith CLI / metalsmith.json

This plugin won't work in metalsmith CLI mode.

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.

demo

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

options

nil

plugin compatibility

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.

testing

nil.

building

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

npm run watch

Author

Levi Wheatcroft [email protected]

Contributing

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

License

MIT : http://opensource.org/licenses/MIT