A Typescript-based template for developing Typescript libraries, with sensible defaults.
This is a template repository for bootstrapping a TypeScript library. It comes pre-configured with useful npm scripts and continuous integration (CI) workflows for quality checks, unit tests, and package releases. The repository is set up to publish packages to GitHub Packages, but it can easily be adapted to publish to other package registries like npm.
To use this template, simply click the "Use this template" button on the GitHub repository page and follow the prompts to create a new repository based on this template.
- Parcel: Blazing fast, zero configuration web application bundler
- Jest: Delightful JavaScript testing framework
- Rome: Unified developer tools for JavaScript, TypeScript. Used for linting, and formatting.
- Lefthook: Fast and powerful Git hooks manager for any type of projects
- nvm: Node Version Manager
This template comes with a set of sensible default configurations for you to use. These defaults can be found in the following files:
├── .gitignore
├── .npmignore
├── .nvmrc
├── .jest.config.mjs
├── lefthook.yml
└── rome.json
This repository uses npm to manage dependencies and run scripts. To install the dependencies, run the following command in the root directory of the repository:
npm install
This template can easily be adapted to work with others package registries like pnpm or yarn.
The project uses parcel to build and bundle the code. To build the project, you can use the following command:
npm run build
This template comes with GitHub Actions pre-configured.
- quality-checks: runs the build command, the linter and the formatter
on every push and pull request made to the
main
branch. - tests: runs the tests onsevery push and pull request made to the
main
branch. - release-package: creates a new release every time you push a new tag to
the repository. This action is only triggered on tags starting with
v
. Once the release is created, the action is also in charge of deploying the documentation to thegh-pages
branch. THIS ACTION NEEDS AN ACTION FROM YOUR SIDE TO WORK - tests-coverage: runs the tests and generates a coverage report on every pull
request made to the
main
branch. A comment is posted on the pull request with the coverage report.
You can edit the CI scripts in the workflows directory.
The release action is in charge of deploying the documentation to the gh-pages
branch. To do so, it needs to have a
personal access token with the right permissions. To create this token, go to the
settings of your Github account. Make sure to select the permissions
listed below. Once create, copy the token, go to the Github repository of this project and create a secret named
RELEASE_TOKEN
with the value of the token you just created. Here are the repositories permissions required by the
token:
- Actions: Read and write
- Contents: Read and write
- Commit statuses: Read-only
- Metadata: Read-only
- Pull requests: Read-only
This project uses Lefthook
to manage Git hooks. Git hooks are scripts that run automatically when certain Git events occur, such as committing code or pushing changes to a remote repository. Lefthook
makes it easy to manage and run any type of scripts.
After installing the dependencies, you can configure the Git hooks by executing the following command in the project directory:
npm run hooks:install
This command installs a Git hook that runs Lefthook before pushing code to a remote repository.
Once the hook is installed, it will automatically run Lefthook before pushing code to a remote repository. If Lefthook fails, the push will be aborted.
To run Lefthook manually, you can use the following command:
npm run hooks
This will run all the Git hooks defined in the lefthook.yml file.
If you need to skip the pre-push hook instaled by lefthook on purpose, you can pass the --no-verify
flag to the push command. For example:
git push origin --no-verify
The unit tests are located at the root of the tests
directory. They are automatically run by GitHub Actions on every push to the main
/prod
branches and on every pull request that targets the same branches. They are also automatically run by the git hook on every push to a remote repository if you installed it (refer to the Git hooks section). Finally, you can also run them locally by executing the following command in the project directory:
npm run test
For you information, Jest is already configured as you expect it. Nothing else is required to run the tests.
For the quality, this template uses rome. It is a linter, and a formatter. It is a single tool that unifies many of the tools you already use. It is designed to replace ESLint and Prettier. Rome already works as expected, the configuration is located in the rome.json file.
To run the linter in check mode run the following command:
npm run lint
To run the formatter in check mode run the following command:
npm run lint:format
Finally, to run the linter and formatter in write mode run the following command:
npm run lint:write
This template uses nvm to manage the Node version. It is configured to use the version specified in the .nvmrc file. The version has been set to the latest LTS version. If you and your contributors use nvm, you can simply run the command below in the project directory to use the correct version of Node. Read the nvm documentation if you want to automatically use the correct version of Node when you enter the project directory.
nvm install && nvm use
Refer to the contributing guidelines for more information.
This project is licensed under the Apache License 2.0. You are free to use, modify, and distribute this software under the terms of the license. See the LICENSE.md file for more details.