TypeScript Boilerplate for 2022


TypeScript project boilerplate with modern tooling, for Node.js programs, libraries and browser modules. Get started quickly and right-footed 🚀

* TypeScript 4
* Optionally esbuild to bundle for browsers (and Node.js)
* Linting with typescript-eslint (tslint is deprecated)
* Testing with Jest (and ts-jest)
* Publishing to npm
* Continuous integration (GitHub Actions / GitLab CI)
* Automatic API documentation with TypeDoc

See also the introduction blog post: Starting a TypeScript Project in 2021.

Getting Started

``bash

Clone the repository (you can also click "Use this template")

git clone https://github.com/metachris/typescript-boilerplate.git your_project_name
cd your_project_name

Edit package.json and tsconfig.json to your liking

...

Install dependencies

yarn install

Now you can run various yarn commands:

yarn cli
yarn lint
yarn test
yarn build-all
yarn ts-node
yarn esbuild-browser
...
`

* Take a look at all the scripts in package.json
* For publishing to npm, use yarn publish (or npm publish)

esbuild

esbuild is an extremely fast bundler that supports a large part of the TypeScript syntax. This project uses it to bundle for browsers (and Node.js if you want).

`bash

Build for browsers

yarn esbuild-browser:dev
yarn esbuild-browser:watch

Build the cli for node

yarn esbuild-node:dev
yarn esbuild-node:watch
`

You can generate a full clean build with yarn build-all (which uses both tsc and esbuild).

* package.json includes scripts for various esbuild commands: see here
* esbuild has a --global-name=xyz flag, to store the exports from the entry point in a global variable. See also the esbuild "Global name" docs.
* Read more about the esbuild setup here.
* esbuild for the browser uses the IIFE (immediately-invoked function expression) format, which executes the bundled code on load (see also https://github.com/evanw/esbuild/issues/29)

Tests with Jest

You can write Jest tests like this:

`typescript
import { greet } from './main'

test('the data is peanut butter', () => {
expect(1).toBe(1)
});

test('greeting', () => {
expect(greet('Foo')).toBe('Hello Foo')
});
`

Run the tests with yarn test, no separate compile step is necessary.

* See also the Jest documentation.
* The tests can be automatically run in CI (GitHub Actions, GitLab CI): .github/workflows/lint-and-test.yml, .gitlab-ci.yml
* Take a look at other modern test runners such as ava, uvu and tape

Documentation, published with CI

You can auto-generate API documentation from the TypeScript source files using TypeDoc. The generated documentation can be published to GitHub / GitLab pages through the CI.

Generate the documentation, using src/main.ts as entrypoint (configured in package.json):

`bash
yarn docs
`

The resulting HTML is saved in docs/.

You can publish the documentation through CI:
* GitHub pages: See .github/workflows/deploy-gh-pages.yml
* GitLab pages: .gitlab-ci.yml`

This is the documentation for this boilerplate project: https://metachris.github.io/typescript-boilerplate/

References

* Blog post: Starting a TypeScript Project in 2021
* TypeScript Handbook
* tsconfig docs
* esbuild docs
* typescript-eslint docs
* Jest docs
* GitHub Actions, GitLab CI

Feedback

Reach out with feedback and ideas:

* twitter.com/metachris
* Create a new issue