commitlint eslint github-actions prettier semantic-release typescript

typescript-project

Template for creating TypeScript projects with no configuration

This project is made with TypeScript v3.7, NodeJS v13 and NPM v6 but should work with newer versions too.

Setup

Creating repository using template

Use this template by pressing the big green button saying "Use this template".

To use all the style checks and rules, install the development dependencies using npm install.

Updating files

Make sure that you update the files to match your new project:

package.json - name, description and urls
package-lock.json - name (simply update the package.json file and run npm install)
README.md - replace with new file
LICENSE.md - update license

Branch protection (optional)

Make sure that the branches the release action triggers on are protected on GitHub. That way in order for any code to get into a release, the code will have to be pass the tests and be approved.

Setup as module (optional)

The template is set up as an application, but it can be configured to be a module which can be automatically published using semantic-release.

In the package.json file, remove the private property. This will make semantic-release publish new releases using npm.

You can publish to GitHub Packages, or to the npm registry.

Publish to NPM

To publish to npm you need to add an npm access token. This token will be used to publish the package. Create a token and add it as a secret to the GitHub repository called NPM_TOKEN.

Publish to GitHub Packages

To publish to GitHub Packages you need to tell npm that you want to publish to the GitHub registry. This can be done in the package.json:

{
    "publishConfig": {
        "registry": "https://npm.pkg.github.com/"
    }
}

When publishing to GitHub Packages you need to authenticate just like if you were using the npm registry. You can either create a personal access token on GitHub with the proper scopes and add that to the secrets with the name NPM_TOKEN, or you can use the access token that is generated on each workflow run. For more information about tokens see here.

The easiest would be to use the token GITHUB_TOKEN that is created on each GitHub Actions workflow run. To do this, simply modify .github/workflows/release.yml by replacing

NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

with

NPM_TOKEN: ${{ secrets.GITHUB_TOKEN }}

When using GitHub Packages you need to use scoped package names. See the documentation for publishing a package on GitHub.

Installing private dependencies

Say you have a private package which relies on another private package that you have made and published. You need to specify where the private package is located, and you needd to authenticate to the package registry.

If you are publishing to GitHub Packages, then you need to update the workflow files so that when installing dependencies it will authenticate with the registry for your own scope.

  uses: actions/setup-node@v1
  with:
    node-version: ${{ matrix.node-version }}
    registry-url: https://npm.pkg.github.com/
    scope: '@nicklason'

Set registry-url to https://npm.pkg.github.com/, and scope to your own scope, for example mine is @nicklason.

You need to have a personal access token that have the scopes read:packages and repo. Add it to the environment variables for when installing dependencies.

- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.READ_PACKAGES_PAT }}

Add the personal access token to the secrets of the repository with the name READ_PACKAGES_PAT.

In the release workflow file you also need to add NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} to the environment variables for the release step.

Configuration

This template works out of the box as an easy way to create a new TypeScript project, no configuration is required for basic usage.

Development environment

If you have your own preferences, you can modify the configuration for the different dependencies.

Dependencies used:

ESLint - validate code style using rules
Prettier - automatically format code
Commitizen - easily create commit messages to follow commit conventions
Commitlint - validate commit messages
Husky - git hooks
lint-staged - run linters against staged git files

Publish to npm registry (optional)

Semantic-release can be used to automatically publish to an npm registry. By default this template is set up as an application, and not a module, but can be configured into automatically publishing packages.

Usage

This template is designed to work with Visual Studio Code. In order to work properly you should install the following extentions:

Writing code

When you are writing code you will be able to see warnings from ESLint and TypeScript if your style / code is bad. TypeScript files will be formatted on save using Prettier.

Committing code

Create a commit by staging the files and then running the command npm run commit. All it does is provide you a command-line way of creating commit messages that will follow the convention.

You can also manually create a commit, just make sure that you are following the commit message convention.

When making a commit you can get a warning. This warning is a result of one of the husky hooks exiting with an error. To see the error, see the output / click on the "Open git log" button.

Making releases

Releases are made automatically and version changes are determined by commit messages - this is why it is important to use npm run commit when making commits.

When new code is pushed to one of the release branches (master, next, next-major, alpha, beta) then the release action will be triggered and a new version will be made based on the commit messages.

If the release action determines that a new version should be made, then it will update the version inside the package.json and package-lock.json files and make a new release on GitHub.

This template can be configured to also publish modules with npm.

For more information about automated releases, see the documentation for semantic-release.

Final notes

Everything will (hopefully) just work.

About