📚 All guides and package documentation.
This document explains some of the global setup and tooling. Each package workspace may have its own additional setup and tooling.
Finch always supports >= the oldest Node.js LTS version. Issues running against older Node.js versions are immediately closed. Issues running against newer Node.js versions are addressed as time permits.
Node Version Manager (NVM) is used ensure the application is developed against a known Node.js version. Begin by setting up NVM. Next follow NVM's onscreen directions:
nvm use
Install and hoist the package dependencies.
yarn
See the packages themselves for other setup instructions.
General tooling instructions follow below. Refer to these other documents for other specific tooling use cases:
Execute all specs (unit tests) defined in .spec.js
files using Jest. See Jest API documentation for information on authoring tests.
yarn test
Test specs for a specific package workspace:
yarn test packages/{workspace}/
Jest arguments can be passed to yarn test
as seen below:
yarn test --watch
Use the Node.js debugger to step through specs.
yarn test:debug
Avoid the
--watch
Jest behavior when usingtest:debug
. As of Jest 24 it doesn't work consistently with debugging.
Modules can support spec-specific behavior by using the snippet below:
if (process.env.NODE_ENV === "test") {
// This condition is only met while within Jest's runner.
}
Lint source files:
yarn lint
Include
--fix
argument to automatically fix lint errors when possible
Linting and code style are strictly enforced. Prettier is used to format all project files. Pre-commit hooks lint and fix .js
, .html
, and .md
files. Please configure your editor to provide lint feedback while editing and formatting on save.
See the packages themselves for other tooling instructions.
Run the main script file for {package}
using nodemon
. The script file is re-ran anytime a .js
file is changed anywhere below thepackages/
directory.
yarn dev packages/{package}
Same as yarn dev
although execution will wait until the debugger is connected. This is a good read to get familiar with debugging Node.js.
yarn dev:debug packages/{package}
Unfortunately Jest --watch
is sometimes frustratingly inconsistent when the debugger is involved. This workaround is less graceful but functional.
The following is tested on macOS:
- Install the Chrome NiM plugin
- Configure the plugin to automatically open developer tools
- Place a
debugger
statement where you would like to begin debugging - Run
yarn test:debug
- Click in the Chrome window, NiM should open developer tools
- Allow the debugger to continue (use
Meta+\
shortcut on macOS) - The debugger should stop at the
debugger
statement from above - Perform your debugging, breakpoints are maintained between runs
- To run again press
Ctrl+C
from the Jest terminal to break the debugger connection - Make your code changes
- Re-run
yarn test:debug
- Click back into the Chrome window, NiM should re-open developer tools
- Repeat
- Log into to NPM and
@finch
scope:npm login --scope=finch
- Interactively determine new version number for packages and keep the result local for review:
yarn lerna version --no-push
- Publish the latest package versions:
yarn lerna publish from-package
🐦