Skip to content

Latest commit

 

History

History
199 lines (133 loc) · 7.26 KB

README.md

File metadata and controls

199 lines (133 loc) · 7.26 KB
Raw

Node Browsers Mastodon Medium

Automated development tasks (linting, testing, building) for JavaScript/TypeScript code (Node.js and/or browsers).

This is used in my own projects. This is not meant to be shared and semantic versioning is not followed.

The task runner is Gulp, but you don't need to know Gulp to use these tasks.

Also, Docker must be installed globally and executable by the current user without sudo.

Hire me

Please reach out if you're looking for a Node.js API or CLI engineer (11 years of experience). Most recently I have been Netlify Build's and Netlify Plugins' technical lead for 2.5 years. I am available for full-time remote positions.

Workflow

Code is compiled from the src to the build directory using Babel, so you can use the latest JavaScript features.

Linting and formatting are performed with ESLint, Prettier, Jscpd and lychee. We recommend using plugins with your IDE (code editor) for both Prettier and ESLint so that linting/formatting is performed as you code.

We use Ava to run tests. Each line of code must be tested.

We use tsd to test TypeScript types. Each export must be fully typed using either TypeScript regular files (*.ts) or ambient files (*.d.ts).

Usage

Any task can be run using gulp for example:

gulp build

If you're on cmd.exe (Windows) use npx gulp ... instead.

Overview

The main commands are:

  • gulp build: build source files and test files. Must be run before running any code or unit tests.
  • gulp check: lint/format the JavaScript and TypeScript files.
  • gulp type: run TypeScript type tests.
  • gulp unit: run unit tests.
  • gulp test: perform all of the above tasks.

Use gulp buildWatch, gulp typeWatch, and gulp unitWatch to run them in watch mode.

GitHub actions ensures that:

  • tests pass on all supported environments.
  • all source files are covered by tests and follow the same coding style.

Available tasks

gulp build

Build source files and test files:

  • JavaScript and TypeScript files are transpiled with Babel.
  • Other files are copied as is.

Source files and test files are built from the src directory to the build/src directory.

This must be done before linting or running any code or unit tests.

To add TypeScript types, use either:

  • Regular TypeScript files (*.ts). An ambient file is automatically created by tsc --declaration.
  • JavaScript files (*.js) and ambient files (*.d.ts). Ambient files are copied as is.

gulp check

Lint and check source files:

gulp type

Run TypeScript type tests with tsd. The type tests must be named *.test-d.ts.

gulp unit

Run unit tests with Ava. The test files must be named *.test.js.

To specify Ava options, please call ava directly instead. For example: ava --update-snapshots.

To target a single test file, use ava build/test/file.test.js not ava test/file.test.js.

gulp test

Runs gulp build then gulp check then gulp type and gulp unit.

This is performed on CI (GitHub actions) for each OS (Windows, Mac, Linux) and supported Node.js version.

gulp buildWatch, gulp typeWatch, gulp unitWatch, gulp warnWatch

Like gulp build, gulp type, gulp unit and gulp warn but in watch mode. The watch mode works even when installing/updating/uninstalling dependencies or changing the Gulp tasks themselves.

They can be performed together, e.g. gulp buildWatch in one terminal tab and gulp unitWatch in another.

Other tasks

gulp links

Detect dead links with lychee.

gulp warn

Check for security vulnerabilities (using npm audit) and outdated dependencies (using npm outdated).

gulp releasePatch, gulp releaseMinor, gulp releaseMajor

Release a new patch/minor/major version on npm and GitHub using release-it.

npm publish must be performed locally afterwards.

Only the repository owner can perform these tasks.

gulp unitCoverage

Like gulp unit but also compute test coverage.

Custom tasks

Repositories with a gulp top-level directory have additional tasks. Please check those files to see which custom tasks are available.

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug, please check our guidelines. Pull requests are welcome!