Skip to content

Latest commit

 

History

History
138 lines (92 loc) · 4.13 KB

Developer Guide.md

File metadata and controls

138 lines (92 loc) · 4.13 KB
Raw

📚 All guides and package documentation.

Developer Guide

This document explains some of the global setup and tooling. Each package workspace may have its own additional setup and tooling.

Setup

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.

Tooling

General tooling instructions follow below. Refer to these other documents for other specific tooling use cases:

Specs

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 using test: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

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.

Debugging tips

Direct development

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}

Spec debugging

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:

  1. Install the Chrome NiM plugin
  2. Configure the plugin to automatically open developer tools
  3. Place a debugger statement where you would like to begin debugging
  4. Run yarn test:debug
  5. Click in the Chrome window, NiM should open developer tools
  6. Allow the debugger to continue (use Meta+\ shortcut on macOS)
  7. The debugger should stop at the debugger statement from above
  8. Perform your debugging, breakpoints are maintained between runs
  9. To run again press Ctrl+C from the Jest terminal to break the debugger connection
  10. Make your code changes
  11. Re-run yarn test:debug
  12. Click back into the Chrome window, NiM should re-open developer tools
  13. Repeat

Releasing

  • 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

🐦