@talkapps/ts-unified

ts-unified

Boilerplate-as-a-package for TypeScript-based projects.

Features

• Compilation with Babel.
• Type-checking and declaration generation with TypeScript.
• Unit testing with Jest.
• Linting with ESLint.
• Version and change log management with standard-version.
• Package script management with NPS.

Usage

npm install --save-dev @talkapps/ts-unified

This repository provides most of the build and code quality tooling needed for modern TypeScript-based projects. It also provides several common package scripts for building, testing, and versioning a project. These scripts are provided via NPS. For more information, see the NPS section below.

Configuration Files

This section will walk you through setting up the configuration files required by the various tools that ts-unified provides support for. Each base configuration file is provided as a function that accepts an optional additional configuration object that will be merged with the default configuration, allowing projects to extend or modify the base configuration.

NPS

In your project root, create package-scripts.js. Then, export the NPS configuration from ts-unified, optionally providing your own configuration/scripts to merge with the defaults.

💡 PROTIP: NPS does not provide a native extends feature, so configuration merging is achieved by passing an object containing your configuration to the function exported by package-scripts. If you do not need to provide any additional configuration, you still need to invoke this function to ensure the correct object is exported by your configuration file.

package-scripts.js

Using base configuration:

module.exports = require('@talkapps/ts-unified/dist/config/package-scripts')();

Providing additional configuration:

module.exports = require('@talkapps/ts-unified/dist/config/package-scripts')({
  scripts: {
    foo: {
      description: 'My awesome script.',
      script: 'foo --bar --baz'
    }
  }
});

Once you have created this file, you can get a list of all NPS scripts provided via ts-unified by running the following command:

npx nps --scripts

Jest

In your project root, create jest.config.js. Then, export the Jest configuration from ts-unified, optionally providing your own configuration to merge with the default.

💡 PROTIP: Jest does not provide a native extends feature, so configuration merging is achieved by passing an object containing your configuration to the function exported by jest. If you do not need to provide any additional configuration, you still need to invoke this function to ensure the correct object is exported by your configuration file.

jest.config.js

Using base configuration:

module.exports = require('@talkapps/ts-unified/dist/config/jest')();

Providing additional configuration:

module.exports = require('@talkapps/ts-unified/dist/config/jest')({
  collectCoverageFrom: [
    '<rootDir>/my-custom-path'
  ]
});

TypeScript

In your project root, create tsconfig.json. Then, extend the TypeScript configuration from ts-unified, optionally providing your own configuration. It is recommended that you at least set baseUrl, outDir, and paths; these cannot be set by ts-unified because TypeScript computes them relative to the tsconfig.json file from which they were declared.

tsconfig.json

Using base configuration:

{
  "extends": "./node_modules/@talkapps/ts-unified/dist/config/tsconfig.json",
  // You should specify at least the following configuration options, as
  // TypeScript resolves these directories relative to the tsconfig.json file
  // where they were defined.
  "compilerOptions": {
    "baseUrl": ".",
    "outDir": "dist",
    "paths": {
      "*": ["*", "src/*"]
    }
  }
}

ESLint

In your project root, create .eslintrc.js. Then, extend the ESLint configuration from ts-unified, optionally providing your own additional configuration.

.eslintrc.js

module.exports = {
 extends: [
    require.resolve('@talkapps/ts-unified/dist/config/eslint')
  ]
}

React Rules

If you're working in a React project, ts-unified provides a React variant of its ESLint rules. To use these rules, extend eslint-react:

.eslintrc.js

module.exports = {
 extends: [
    require.resolve('@talkapps/ts-unified/dist/config/eslint-react')
  ]
}

Running Scripts

For a list of all scripts provided by ts-unified, make sure you have created a package-scripts.js file in your project root per the instructions above. Then, you may run:

npx nps --scripts

Building

To build your project, assuming its source is located at src and build artifacts are to be written to dist, you may run:

npx nps build

or add the following to your package.json:

"scripts": {
  "build": "nps build"
}

and run:

npm run build

To continuously build the project in watch mode:

npx nps build.watch

or:

"scripts": {
  "build:watch": "nps build.watch"
}

npm run build:watch

Testing

To run unit tests for your project, assuming your test files end in .spec.ts, you may run:

npx nps test

or, add the following to your package.json:

"scripts": {
  "test": "nps test"
}

and run:

npm test

To continuously run tests in watch mode:

npx nps test.watch

or:

"scripts": {
  "test:watch": "nps test.watch"
}

npm run build:watch

To run unit tests and generate a coverage report:

npx nps test.coverage

or:

"scripts": {
  "test:coverage": "nps test.coverage"
}

npm run test:coverage

Versioning

To generate (or update) a CHANGELOG.md and bump the project's version, assuming you use Conventional Commits, you may run:

npx nps bump

or, add the following to your package.json:

"scripts": {
  "bump": "nps bump"
}

and run:

npm run bump

Alternatively, if you need to create a beta tag:

npx nps bump.beta

or:

"scripts": {
  "bump:beta": "nps bump.beta"
}

npm run bump:beta

NPM Life Cycles

ts-unified also provides a prepare script that will build and test the project. If you wish to use this script, add a prepare script to your project's package.json:

"scripts": {
  "prepare": "nps prepare"
}

This script will then be run after every npm install and as part of every npm publish command.