flow-brunch

Adds Flow support to Brunch.

• Installation
• Overview
  • status method (default)
  • check-contents method
• Optional configuration
• License

Installation

Install the plugin:

npm install --save-dev flow-brunch

Ensure you have a .flowconfig file in the root directory of your Brunch project:

touch .flowconfig

If you haven't already, you'll need to configure Brunch to strip Flow annotations.  For example:

npm install --save-dev babel-brunch
npm install --save-dev babel-plugin-transform-flow-strip-types
 
echo '{ "plugins": ["transform-flow-strip-types"] }' > .babelrc

Overview

Brunch's linting API is designed for linters like ESLint which operate on individual files in isolation, but Flow is designed to operate on a complete codebase and check the interconnections between all the files.

To work around this issue, this plugin provides a choice of two different methods for executing Flow, each of which has advantages and disadvantages:

	status (default)	check-contents
ℹ️	Executes flow status to ask the Flow server for the current errors for the complete codebase, and then applies a filter to only report the errors relating to the specified file.	Executes flow check-contents to manually check the specified file and its dependencies.
✅	Errors in all files interconnected with the specified file are detected and reported.	There's no race condition, so no pre-lint delay needs to be applied.
❌	The existence of a race condition requires a pre-lint delay to be applied, which increases the execution time of the plugin (see below).	Errors in files which depend on the specified file are not detected or reported (see below).

status method (default)

When brunch watch is running, modifying a source file initiates a race condition between Brunch's build pipeline and the Flow server.  If Flow loses the race (ie: if the Brunch build pipeline executes this plugin before Flow has finished rechecking the file), then any new errors won't be reported.

⚠️  To avoid this issue, the plugin needs to apply a pre-lint delay to ensure Flow always wins the race.  This increases the execution time of the plugin, which goes against Brunch's philosophy of the paramount importance of speed.

The default delay is 250 milliseconds.  If you observe Flow losing the race, then increase the delay in the configuration.

check-contents method

Consider these two example files:

foo.js

// @flow
 
const bar = require('./bar.js');
 
bar('test');

bar.js

// @flow
 
module.exports = function (x: string) {
    console.log(x);
};

If brunch watch is started, and then function (x: string) is modified to function (x: number) in bar.js:

// @flow
 
module.exports = function (x: number) {
    console.log(x);
};

then the plugin executes flow check-contents on bar.js.

⚠️  However, foo.js is not rechecked, because flow check-contents doesn't check any files which depend on bar.js, and so the new error of calling bar('test') in foo.js (with a string instead of a number) won't be detected or reported.

Optional configuration

Place the following code within the plugins section of your brunch-config.js file:

flowtype: {
    warnOnly:    false,
    method:      "status",
    statusDelay: 250
}

All configuration items are optional.

Config	Type	Default	Description
warnOnly	Boolean	false	If true, then linting issues will be reported as warnings instead of errors, allowing Brunch's build pipeline to continue compiling the affected file(s).
method	String	"status"	Method for executing Flow (either "status" or "check-contents") – see here.
statusDelay	Number	250	Pre-lint delay (in milliseconds) for the "status" method – see here.

License

Licensed under the MIT license.