Node.JS TypeScript Library Template

This is a template repository meant to be used as a starting point for new Node.JS projects written in TypeScript.

As this is a highly opinionated template, many tools are included and pre-configured with sane and strict defaults to enforce a standard level of code quality and a consistent style across projects.

With this in mind, feel free to edit the various config files to your liking.

Prerequisites

To view static documentation and coverage reports, http-server is recommended; it is included as a development dependency for the serve:* commands, but for manual CLI usage, install it with npm i -g http-server.

Setup

pnpm is used as the package manager; install it with npm i -g pnpm if you do not already have it.

Then, to get started, simply install dependencies with pnpm i.

Building Sources and Documentation

Three npm scripts are provided to build TypeScript sources and generate documentation with TypeDoc:

• build -- runs both build:ts and build:docs.
• build:ts -- builds TypeScript sources from ./src to native JavaScript files in ./dist.
• build:docs -- builds documentation with TypeDoc in ./docs. Both LICENSE.md and CHANGELOG.md are copied into ./docs.

Viewing Documentation Site

After building the static HTML documentation with build:docs, run pnpm serve:docs or http-server docs and navigate to localhost:8080.

Deploy Documentation On GitHub Pages

To enable GitHub Pages, access the repository settings and configure the Pages settings to use the main (or master) branch and the ./docs folder.

Testing

Testing is done with mocha and chai. nyc is used to generate coverage reports. The following npm scripts are provided:

• test -- runs mocha on all TypeScript sources
• test:coverage -- like test but runs nyc to generate an HTML coverage report in /coverage.
• test:watch -- runs nyc and mocha continuously, re-running tests when any sources change.

Viewing Test Coverage Report

After generating an HTML coverage report with test:coverage, view it by running either serve:coverage or http-server ./coverage and navigating to localhost:8080.

Linting

Linting is provided by ESLint and markdownlint. The following npm scripts are provided:

• lint:eslint -- runs ESLint on ./package.json and ./src/**/* and prints any errors.

• lint:markdownlint -- runs markdownlint on README.md and prints any errors.

• lint:eslint:fix -- like lint:eslint but automatically fixes linter errors where possible.

• lint:markdownlint:fix -- like lint:markdownlint but automatically fixes linter errors where possible.

• lint -- runs both lint:eslint and lint:markdownlint.

• lint:fix -- runs both lint:eslint:fix and lint:markdownlint:fix

ESLint Config & Plugins

A strict ESLint config is provided with many plugins, the full list is below:

• eslint-plugin-chai-expect -- ESLint plugin that checks for common chai.js expect() mistakes.
• eslint-plugin-eslint-comments -- ESLint rules for JavaScript comments.
• eslint-plugin-github -- An opinionated collection of ESLint rules used by GitHub.
• eslint-plugin-immutable -- This is an ESLint plugin to disable all mutation in JavaScript.
• eslint-plugin-json-format -- ESLint plugin for JSON files.
• eslint-plugin-jsonc -- This ESLint plugin provides linting rules relate to better ways to help you avoid problems when using JSON, JSONC and JSON5.
• eslint-plugin-lodash -- Lodash-specific linting rules for ESLint.
• eslint-plugin-mocha -- ESLint rules for mocha.
• eslint-plugin-no-secrets -- An ESLint rule that searches for potential secrets/keys in code and JSON files.
• eslint-plugin-optimize-regex -- Optimize regex literals.
• eslint-plugin-promise -- Enforce best practices for JavaScript promises.
• eslint-plugin-pure -- Enforce rules to make your code purely functional by disallowing some language constructs.
• eslint-plugin-regexp -- An ESLint plugin for finding RegExp mistakes and RegExp style guide violations.
• eslint-plugin-sonarjs -- SonarJS rules for ESLint to help developers produce Clean Code by detecting bugs and suspicious patterns.
• eslint-plugin-switch-case -- Switch-case-specific linting rules for ESLint.
• eslint-plugin-tsdoc -- This ESLint plugin provides a rule for validating that TypeScript doc comments conform to the TSDoc specification.
• eslint-plugin-unicorn -- More than 100 powerful ESLint rules
• eslint-plugin-write-good-comments -- Enforce good writing style in your comments.

Formatting

Prettier is included to automatically format sources to enforce a consistent and standardized code style. It automatically verifies that sources conform to the standard style as part of the Husky pre-commit hook.

Two scripts are provided:

• format -- runs Prettier and formats files in-place.
• format:check -- runs Prettier in check mode, reporting any files that do not match the standard style. To fix any reported issues, use the format script.

Husky

Husky hooks are automatically installed when pnpm i is run.

Husky is included and configured with two commit hooks:

• pre-commit: runs lint-staged, which runs markdownlint and ESLint on README.md and project sources in src/**.
• commit-msg: runs commitlint on commit messages to enforce the conventional commit standard.

Creating A New Project

To start a new project with this repository as a template, clone it and delete the .git folder, then run git init . to start a new git project and commit history.

Then, configure package.json with your project name, description, keywords, repository URL, version number, and any other details you wish to change.

Add code to ./src, and it will be built to ./dist. ./src/index.ts will be built as the project entry point at ./dist/index.js as defined in the manifest.

CI

After each push to the main branch, the CI GitHub Action runs to ensure all checks pass.

Releasing

To release a new version of your package, the release npm script is provided. It does the following:

• runs pnpm format:check
• runs pnpm lint
• runs pnpm test
• runs pnpm build,
• runs git add docs
• Updates the package.json version appropriately based on the commits made since the last release.
• Updates the CHANGELOG.md.
• Commits all changes and tags the commit with the new version number.
• Pushes main with the new tag to origin.
• Triggers the NPM Publish workflow to automatically publish the new version on the NPM Registry.

Available scripts are:

• pnpm docs: generate HTML documentation in ./docs
• test: run mocha on all tests in ./src/tests
• test:coverage: run mocha and generate a coverage report in ./coverage
• build: build to JS in ./dist
• lint: run eslint on all files in ./src
• update-deps: update all dependencies
• update-version: updates the CHANGELOG.md, bumps the version, commits & tags
• release: lints, tests, builds, generates docs, runs update-version and pushes.

Publishing

Publishing to the NPM Registry is done automatically with a NPM Publish GitHub Action that runs when a new tag is pushed. For this to work, you must add a secret named NPM_TOKEN to the repository settings.

Release History

See CHANGELOG.md for more information.

License

Distributed under the MIT license. See LICENSE.md for more information.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request