Whys-scripts NPM

Whys scripts

Consistent JavaScript tooling on many projects with ease, so you can focus on your product.

What is not easy:

inconsistent file patterns for all the tools
tackling compatible package versions (if a tool is composed from many or reuses packages such as babel)
installing and setting up "devDependencies" for each project
tooling decisions made on each project
consistent tooling between projects

Get started

# add or upgrade
yarn add --dev whys-scripts
# initialize/update config in package.json
whys-scripts init

Running the init script and following our conventions you get immediate linting and formatting in your editor (as it exports config files). Scripts to run lint/format/test locally or in CI will be available for your needs.

Configuration in `package.json`

field `src` (array)

Specify your source files.

Examples:

"pages/**/*.js": whole tree of files with .js extension in pages directory of package root
"*.js": files with .js extension in package root
"!src/templates/**/*.js": excludes files with .js extension in the subdirectory tree
"!**/__generated__/**": to exclude relay-generated files (they are generated next to source)

Usage:

{
  "whys-scripts": {
    "src": ["pages/*.js", "components/*.js"]
  }
}

field `tests` (array)

Specify how to find test files. Example below shows defaults.

Usage:

{
  "whys-scripts": {
    "tests": ["src/**/*.test.js", "tests/**/*.js"]
  }
}

field `projectType` (enum)

Its used to determine which configs to use. Project type can be one of these values:

react-application (default when whys-scripts init is run)
react-library
node-library

{
  "whys-scripts": {
    "projectType": "react-application"
  }
}

field `enable`

Its an object used to enable flags.

Possible flags:

typescript enables TypeScript

{
  "whys-scripts": {
    "enable": { "typescript": true }
  }
}

field `repository` (optional)

An object to change default names of git branch and remote.

Example with default values (behaves same as omitting the field):

{
  "whys-scripts": {
    "repository": { "branch": "main", "remote": "origin" }
  }
}

It's used to determine changed files in scripts with --changed option.

script `init`

npx whys-scripts init

Updates your npm project to use whys-scripts. It adds default config for the whys-scripts field in package.json. Config dot files are copied to your project root.

script `format`

npx whys-scripts format

Formats the source code. Mostly based on airbnb styleguide.

script `format-check`

npx whys-scripts format-check

Checks all the source code was formatted.

script `lint`

npx whys-scripts lint

Runs eslint on the source code. There are no formatting rules and a few stylistic rules as warnings.

To fix problems you can run:

npx whys-scripts lint --changed --fix

strict version

npx whys-scripts lint --strict

The script will treat warnings as errors. It will exit with non-zero status code on any warning.

script `test`

npx whys-scripts test

Tests your react app or library with jest.

You can run tests in watch mode: test --watch. To create coverage report, run: test --coverage.

script `export-eslint-config`

npx whys-scripts export-eslint-config

Creates .eslintrc.js file in your project root. It copies configuration that is used in the lint script. This should enable linting directly in your editor.

script `export-prettier-config`

npx whys-scripts export-prettier-config

Creates .prettierrc.js file in your project root. It copies configuration that is used in the format script. This should enable correct formatting directly in your editor.

script `init-git-hooks`

It creates git hooks that run "npm scripts" that are conventionally called same as the git hooks.

Notes:

useful for local development, faster feedback loop than CI
adds the hook only if respecting npm script exists
we don't run it in the main init script because it can annoy some people, so you have to init the git hooks yourself (you can always run the npm script)
in case of monorepo it will work only for the root package

Supported hooks:

pre-push is run before pushing to remote
pre-commit is run just before commit is created

Guides

enable TypeScript

To use TypeScript on a new project, run:

npx whys-scripts init --typescript

To use TypeScript on an existing project, run:

npx whys-scripts init --typescript --write

It should update whys-scripts field in package.json with:

{
  "whys-scripts": {
    "enable": {
      "typescript": true
    }
  }
}

also update src and tests to match ts and tsx files:

{
  "whys-scripts": {
    "src": ["src/**/*.{ts,tsx}"],
    "tests": ["src/**/*.test.{ts,tsx}"]
  }
}

usage in monorepo

There is no problem using whys-scripts in a monorepo. We only have more options. For example we can run tests for a single package or run all tests in all packages of the monorepo. It applies to linting and formatting as well.

Lets have packages in standard packages directory.

test one package

In <ROOT>/packages/a/package.json of the package:

{
  "whys-scripts": {
    "src": ["src/**/*.{ts,tsx}"],
    "tests": ["src/**/*.test.{ts,tsx}"]
  }
}

Now you can run npx whys-scripts test from <ROOT>/packages/a to run only tests of the package.

test all packages

In package.json of repository root:

{
  "whys-scripts": {
    "src": ["packages/*/src/**/*.{ts,tsx}"],
    "tests": ["packages/*/src/**/*.test.{ts,tsx}"]
  }
}

Now you can run npx whys-scripts test from <ROOT> to run all tests in the monorepo.

Notes:

just make sure to install only one version of whys-scripts for all packages and for the root package

Running checks on staged/changed files

Its useful to check files before committing them e.g. with git hooks.

Recommended usage with --staged flag:

lint --staged
format --staged --add: format only staged files (can't be partially staged) and stage them again with git add

these scripts can be also used with --changed flag:

lint --changed
format --changed
format-check --changed

A file is considered changed if its latest commit is not on origin/main (by default, see repository) or changes are not committed.

In another words:

this is conventional and cannot be configured
expects remote to be origin
expects main branch to be main

Conventions

You don't have to follow these conventions in order to use whys-scripts. However to achieve consistency between projects and to have little to no configuration its recommended.

test file's name ends with `.test.js`

Because if you name it file_test.js instead of file.test.js, editors tokenize it as one word. That leads to no autocomplete, its harder to navigate a cursor within the name and harder to rename the file.

source code is in `src` directory relative to `package.json`

It makes integration with whys-scripts easier (and other tools as well) because we know everything in directory tree from src is source code, unless specified otherwise.

Compatibility table

This package should work with other toolkits alongside, but sometimes if same packages are installed, it might not. This table documents tested versions of such toolkits.