Typescript Library Starter

This project provides the boilerplate for starting a typescript library to be hosted on npm.

Prerequisites

You will require the following to make use of this boilerplate.

1. Github account.
2. Node.js installed on your local machine and optionally yarn.
3. Git installed on your local machine.
4. An IDE with javascript/typescript support.

Recommended IDE

You should be using Visual Studio Code because its simple, fast, extensible and beloved by many developers.

Make sure to install all the recommended extensions that come with the repository for the best possible coding experience.

Quick Start

If you are not using a npm org it may be a good idea to check if your intended package name is available on the npm registry before starting these steps.

GitHub

1. Create an empty repository for your package on github naming it according to your intended package name.

Local setup

1. Clone the boilerplate using git clone https://github.com/amaya-loves-tea/typescript-library-starter.git YOUR_PACKAGE_NAME.

2. Delete the .git folder as you don't want my history.

3. Install dependencies with yarn or npm install.

4. package.json - Change name, description, repository and author information.

5. .travis.yml - Change the -r parameter of yarn doc:publish command to point to your repository but keep the $GH_TOKEN within the url for e.g https://[email protected]/USERNAME/YOUR_PACKAGE_NAME.git

6. readme.md - There are comments in this readme indicating what you need to change in this file. They look something like this [//]: # 'COMMENT HERE'. Alternatively you can also use the following directions.

   1. Change first heading to YOUR_PACKAGE_NAME.
   2. Badge urls
      • Change all repository urls to point to your repository.
      • Change @teasenshi/ to your npm org or if your are not using a npm org remove it from the urls.
      • Make sure all occurrences of amaya-loves-tea are changed to your USERNAME.

        These badges will stop working but it will be fixed in following sections.

   3. Change the description under the badges to your package description.
   4. Update the npm scripts section to remove notes about registering for certain services.
   5. Delete quick start, prerequisites and all sections after debugging as they are specific to the boilerplate.
   6. Delete all comments in the readme.

7. Git setup instructions

   1. git init - create an empty repository.
   2. git add . - stage all files.
   3. git commit -m "chore(repository): initial commit" - commit staged files with a conventional commit message (more on that later).
   4. git remote add origin https://github.com/USER_NAME/YOUR_REPOSITORY_NAME.git - add a remote to the repository you created earlier.
   5. git push --set-upstream origin master - push your initial commit to the remote (github).

If you forget to do something that you should have done before your initial commit then you can redo it by:

1. Making your changes.
2. Deleting the .git folder.
3. Redoing the steps described above in Git setup instructions. However when pushing add the --force flag to override your initial commit for e.g git push --set-upstream origin master --force.

External Services

Now it's time to fix all the readme badges and set up your build pipeline.

Codecov

Codecov is a service that integrates into various tools, hosts your code coverage reports and is free for public repositories.

1. Login or sign up to codecov using your github account.

2. At https://codecov.io/gh/YOUR_USERNAME choose add repository and add your new repository.

3. Ignore the upload token unless you want to publish coverage reports outside your CI environment.

Travis CI

Travis CI is a continuous integration service where you can create a ci build pipeline and is free for public repositories.

The build pipeline configured with this repository will:

• Test your code and on success perform the following actions
  • Generate and publish your docs to github pages.
  • Generate and publish a code coverage report to codecov.
  • Generate and publish a release on github and npm using semantic release

1. Sign in and authorize travis with your github account.
2. Activate your new repository here.
3. In https://travis-ci.org/USERNAME/YOUR_PACKAGE_NAME/settings:
   1. Create a github personal access token with repo access and add it to your environment variables as GH_TOKEN with master branch access only.
   2. Create a npm authentication token with publish access and add it to your environment variables as NPM_TOKEN with master branch access only.

      The above tokens are for semantic release so it can publish your package on npm.

   3. Trigger your first build from the dashboard which will make your build badge green but not yet deploy your package.

Pushes to the master branch will now automatically run your CI pipeline. You can configure the pipeline using the .travis.yml file.

Greenkeeper

Greenkeeper provides safety and consistency with real-time monitoring and automatic updates your dependencies.

1. Register on greenkeeper and authorize it with your github account.
2. Follow the steps on their documentation to enable greenkeeper on your repository.

Reference Repository

See the first commit on this repository as a reference to the above steps.

NPM Scripts

Note that these examples use yarn but you can use the equivalent npm run <command> instead.

Most of them will automatically run when you perform certain actions on your repository.

Code style

Ensures code consistency in your code base.

These commands automatically get run before commits.

• yarn style - Runs all style:* commands.
• yarn style:lint - Lints your code using eslint.
• yarn style:format - Formats your code using prettier.

Build Tasks

Creates builds from your Typescript files for CommonJS (cjs) and ES6 modules (esm).

• yarn build - Runs all build commands which creates builds for different node environments.
• yarn build:main - Creates a build using cjs modules.
• yarn build:module - Creates a build using esm modules.

Testing

Ensures code is reliable by running your jest unit tests.

Unit tests automatically get run before commits.

• yarn test - Runs all tests and generates a code coverage report.
• yarn test:watch - Watches file changes and reruns tests for those changed files.

Code Coverage

Generates and publishes documentation based on your typedoc comments.

If you sign up to travis and codecov these reports automatically get published after successful builds.

• yarn cov - Generate a code coverage report.
• yarn cov:open - Open generated code coverage report.
• yarn cov:publish - Publish generated code coverage reports to codecov. Running this command locally will require the upload token for e.g yarn cov:publish --token="YOUR_TOKEN_HERE"

Documentation

Generate and publishing documentation based on your typedoc comments.

If you sign up to travis, docs automatically get published to github pages after successful builds.

• yarn doc - Generates documentation from code.
• yarn doc:open - Opens generated documentation in your default browser.
• yarn doc:publish - Publishes generated documentation.

Helpers

These commands perform misc tasks.

• yarn commit - Create a new commit using the commitizen cli.
• yarn clean - Cleans up all build artifacts such as the distribution folder.

Conventional Commits

Commit messages to this repository that don't follow the conventional commit guidelines will be rejected by a commit-msg git hook.

No one likes rejection so use the yarn commit script which provides a CLI interface for creating formated commits.

Git Hooks

If you would like to run custom tasks during important actions on a repository you can use git hooks.

To make this as simple as possible we use husky which is also used in the conventional commits toolchain.

Debugging

The following launch configurations will assist with debugging your library.

• Current TS File - debug current typescript file.
• Current Jest Test - debug current jest test.
• All Jest Tests - debug all jest tests.

Special Sauce

Collect many badges to give your readme that that special something something 😎.

You can also create your own badges to link to any important resources such as your documentation.

Refer to the badges in this readme for examples.