@goodeggs/toolkit

Development toolkit providing scripts for building, linting, testing, and other common tasks Good Eggs modules and applications.

• The Problem
• This Solution
• Installation
• Usage
  • Command Reference
• Development
  • Releases
  • Debugging
• Credits

The Problem

Bootstrapping a single project with development dependencies for linting, testing, and building is a painful problem. Keeping those dependencies up to date and making sure you're following current best practices (across all projects!) is even more time consuming.

This Solution

@goodeggs/toolkit is a single development dependency that abstracts away linters, test tooling, and other scripts you would otherwise duplicate across projects. It includes all dependencies it needs to run (so you don't need to install, for example, eslint to make linting work).

Installation

Install via yarn:

yarn add --dev @goodeggs/toolkit

For setup instructions, see SETUP.md.

Usage

These scripts are intended to be run via yarn run or npm run and replace your current build scripts.

For example, to replace a script that lints JavaScript files, you might make the following changes to your project's package.json#scripts:

  {
    "scripts": {
-     "lint:es": "eslint --ext js,jsx,ts,tsx --ignore-pattern '!.*rc.js' --ignore-path .gitignore .",
+     "lint:es": "getk run lint-es",
    }
  }

Note: getk is designed to be run from the root of your project. Running it via yarn or npm guarantees this; if you run getk explicitly, keep this in mind.

Command Reference

For a full listing of scripts, run getk run --help or check out the commands directory.

Development

This project is built in TypeScript and must be rebuilt via yarn run build whenever any changes are made.

This project includes itself as a dependency (check out package.json#dependencies). That means that when you're working on it, whenever you make changes you'll need to update the copy installed to node_modules/@goodeggs/toolkit. The easiest way to do this is to link the package into itself by running yarn link ; yarn link @goodeggs/toolkit.

If you're making more than a small change, it's recommended you set up a watch task to rebuild the project continuously. The following example uses Watchman (brew install watchman) to do so:

watchman-make -p 'src/**/*.ts' 'src/**/*.js' 'package.json' -r 'yarn run build'

Releasing

To release a new version of this module, use yarn to bump the version in package.json and create a git tag, then push. This will automatically get published to the NPM registry via CI.

yarn version --new-version=<major|minor|patch|premajor|preminor|prepatch>
git push --follow-tags

This project populates the changelog from commit messages via conventional commits. To make this work, commit format is enforced via conventional commits via commitlint. See the conventional commits and commitlint documentation for more information.

To populate the changelog automatically, generate a GitHub token and set CONVENTIONAL_GITHUB_RELEASER_TOKEN in your environment. Next, run:

yarn run release

Debugging

Something unexpected happening? Enable debugging output to see what's going on inside getk:

DEBUG=goodeggs-toolkit* getk <...>

Credits

Inspired heavily by:

• Kent C. Dodds's article Tools Without Config
• kcd-scripts
• react-scripts