A tool for verifying that changes to a package do not affect projects dependent upon it.
Last updated 9 months ago by alexjeffburke .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install fugl 
SYNC missed versions from official npm registry.


NPM version Build Status Coverage Status

A tool for verifying that changes to a package do not affect projects dependent upon it.


Most projects fortunate enough to see wider use end up with a tension between changes that move things forward and consumers that depend on features and behaviours of existing versions.

Fugl intends to provide a way to address that question by providing automation around gaining confidence that forward progress does not come at the expense of compatibility.

Relevant discussion at npm.


Interactively with npx

To check a project currently being worked on the Fugl binary can be invoked via npx. The current directory is scanned for package.json and tested against the listed projects:

npx fugl --projects https://github.com/alexjeffburke/jest-unexpected

You can also specify the npm name of projects and Fugl will try to discover the repository:

npx fugl --projects assert-the-unexpected

Installed as a CLI

The module can also also installed globally or as a project dependency and provides a fugl binary.

npm install -g fugl
fugl --package <packageName>@<packageVersion> --projects https://github.com/someone/somepackage

By default, Fugl will output the success or failure of the tests it performs to the console. You can also specify other reporters, and they correspond to the names of mocha reporters. Perhaps of most interest is the HTML reporter, which will write a self contained breakage report that can be viewed within the browser:

fugl --package unexpected --projects https://github.com/alexjeffburke/jest-unexpected --reporter html

// ...

open breakage/index.html


Fugl supports configuration being supplied to it as a JSON file. This becomes particularly convenient when checking a series of dependents and this list be checked into version control.

Configuration files are loaded by supplying a --config parameter to the fugl binary:

fugl --config .fugl.json

An example basic JSON configuration file would look something like the following:

  "projects": [


When executing tests against a package, a number of hooks are supported to customise and/or extend the commands being executed against each package.

  "projects": [
      "name": "shoulder",
      "test": "npm run coverage",
      "afterinstall": "echo 'directly after package installation'",
      "aftertest": "echo 'directly after executing the tests'"

Automatic dependent fetching

Fugl includes the ability to use various external services to deduce a set of dependents for a package. There are two supported metrics: "downloads" and "stars". These two metrics can be selected by the fetch command.


Fugl will query the npm API for information about package dependents:

fugl fetch downloads --package assert-the-unexpected


Fugl will try to derive the repositories for any supplied projects and then issue queries to GitHub to retrieve the number of stars each project has. Using this is as simple as:

fugl fetch stars --package unexpected

Dependency information via Liraries.IO

One limitation of the npm dependents data is that it only includes information about those packages listed as direct depedents. In order to fetch devDependencies, the tool is also integrated with Libraries.IO.

Signing up for this tool will provide you with an API key which can be used with Fugl as follows:

fugl fetch downloads --package assert-the-unexpected --librariesio <api_key>

Command line interface and chaining

The Fugl CLI is desgined to be helpful and, in the absence of arguments, invocation of the supported commands will result in extensive explanation of supported options and their meaning. These include:

  • fugl check
  • fugl fetch

the Fugl CLI defaults to the check command when executed directly

Chaining via stdin

Configuration for check can also be supplied via stdin. In practice, this means that the output of fetch can be directly piped into using the UNIX shell facilities:

fugl fetch downloads --package unexpected | fugl check --package unexpected


Internally Fugl is implemented as a mocha-esque test runner. As checks are executed events are emitted which are passed into reporters that generate output information. A default reporter is included which outputs to the console.

In the case of the HTML reporter, we use JSDOM as the output document and serialise a report on exit.


This tool started began as a fork of dont-break but the drift of use-cases required a substantial rework and thus Fugl was born. Since then almost the entire codebase has been rewritten.

Compatibility with dont-break

Some effort was made to continue to support users of dont-break. The fugl binary accept a config parameter which can be used to load a dont-break JSON config file:

fugl --config .dont-break.json

As development has continued, previous configurations my require changes as functionality is replaced:

  • config files containing an array of projects at the top level
// .dont-break.json
["project1", "project2"]

// must be rewritten as:
  "projects": ["project1", "project2"]
  • config files containing topDownloads or topStarred
// for topDownloads
fugl fetch downloads

// for topStarred
fugl fetch stars

Current Tags

  • 1.0.0-0                                ...           beta (a year ago)
  • 1.4.1                                ...           latest (9 months ago)

35 Versions

  • 1.4.1                                ...           9 months ago
  • 1.4.0                                ...           9 months ago
  • 1.3.1                                ...           a year ago
  • 1.3.0                                ...           a year ago
  • 1.2.0                                ...           a year ago
  • 1.1.1                                ...           a year ago
  • 1.1.0                                ...           a year ago
  • 1.0.0                                ...           a year ago
  • 1.0.0-1                                ...           a year ago
  • 1.0.0-0                                ...           a year ago
  • 0.12.1                                ...           a year ago
  • 0.12.0                                ...           a year ago
  • 0.11.2                                ...           a year ago
  • 0.11.1                                ...           a year ago
  • 0.11.0                                ...           a year ago
  • 0.10.2                                ...           a year ago
  • 0.10.1                                ...           a year ago
  • 0.10.0                                ...           a year ago
  • 0.9.1                                ...           a year ago
  • 0.9.0                                ...           a year ago
  • 0.8.4                                ...           a year ago
  • 0.8.3                                ...           a year ago
  • 0.8.2                                ...           a year ago
  • 0.8.1                                ...           a year ago
  • 0.8.0                                ...           a year ago
  • 0.7.1                                ...           a year ago
  • 0.7.0                                ...           a year ago
  • 0.6.0                                ...           a year ago
  • 0.5.1                                ...           a year ago
  • 0.5.0                                ...           a year ago
  • 0.4.0                                ...           a year ago
  • 0.3.0                                ...           a year ago
  • 0.2.0                                ...           a year ago
  • 0.1.1                                ...           a year ago
  • 0.1.0                                ...           a year ago
Maintainers (1)
Today 1
This Week 1
This Month 1
Last Day 0
Last Week 0
Last Month 167
Dependencies (14)
Dev Dependencies (11)
Dependents (1)

Copyright 2014 - 2016 © taobao.org |