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 uvu
- 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.
# 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
pnpm install
# Now you can run various pnpm commands:
pnpm cli
pnpm lint
pnpm test
pnpm build-all
pnpm ts-node <filename>
pnpm esbuild-browser
...
- Take a look at all the scripts in
package.json
- For publishing to npm, use
pnpm publish
(ornpm publish
)
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).
# Build for browsers
pnpm esbuild-browser:dev
pnpm esbuild-browser:watch
# Build the cli for node
pnpm esbuild-node:dev
pnpm esbuild-node:watch
You can generate a full clean build with pnpm build-all
(which uses both tsc
and esbuild
).
package.json
includesscripts
for various esbuild commands: see hereesbuild
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 evanw/esbuild#29)
You can write Uvu tests:
import { test } from 'uvu';
import * as assert from 'uvu/assert';
import { greet } from './main'
test('the data is peanut butter', () => {
assert.is(1, 1);
});
test('greeting', () => {
assert.is(greet('Foo'), 'Hello Foo');
});
test.run();
Run the tests with pnpm test
, no separate compile step is necessary.
-
See also the (optinal) Uvu/assert collection . Because uvu operates through thrown Errors (or lack thereof), any Error-based utility can be used as an assertion.
-
The tests can be automatically run in CI (GitHub Actions, GitLab CI):
.github/workflows/lint-and-test.yml
,.gitlab-ci.yml
You can auto-generate API documentation from the TyoeScript 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):
pnpm docs
The resulting HTML is saved in docs/
.
You can publish the documentation through CI:
This is the documentation for this boilerplate project: https://metachris.github.io/typescript-boilerplate/
- Blog post: Starting a TypeScript Project in 2021
- TypeScript Handbook
- tsconfig docs
- esbuild docs
- typescript-eslint docs
- Jest docs
- GitHub Actions, GitLab CI
Reach out with feedback and ideas: