node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



Development server for metalsmith.


  • Consumes the standard metalsmith.json.
  • Consumes metalsmith.js.
  • Auto-recompiles when files are changed.
  • Starts development server and LiveReload.


Run metalsmith-start or metalstart in your Metalsmith's project directory.


See --help for more options.


metalsmith-start honors the following variables:

  • PORT

If either NODE_ENV is set to production, then development features (such as LiveReload) will be disabled by default.

This means that you can run a production setup using:

env NODE_ENV=production PORT=4000 metalsmith-start

This also means you can push your repo to Heroku with no changes and it'll work just fine.

Using metalsmith.js

If a file called metalsmith.js is found in the current directory, it's assumed it's a JS module that returns a Metalsmith instance.

Below is a sample metalsmith.js:

var Metalsmith = require('metalsmith')
var app = Metalsmith(__dirname)
if (module.parent) {
  module.exports = app
} else { (err) { if (err) throw err })


If superstatic.json is found in the current directory, it'll automatically be picked up. This allows you to, say, use cleanUrls to allow pages to be served without the .html extension.

See superstatic for more information.

Programatic usage

var Runner = require('metalsmith-start').Runner
var ms = new Metalsmith(dir)
var r = new Runner(ms)
r.start(function () {
  console.log('started on ' + r.port)


metalsmith-start © 2015+, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors (list).  ·  GitHub @rstacruz  ·  Twitter @rstacruz