This boiler plate exists because I was frustrated trying to init a new TypeScript project and simply use the ora npm package for a command line spinner. This opened up the war of ESM vs CommonJS and I deeply deeply wanted to not have to care about all that nonsense. In the end, I did have to care, but this is the best solution I could find that let's me optimize-out as much caring about that stuff as I can. I also avoid a bable dependency. My goal was a new, modern-for-2021 command line tool that may also be used as a dependency.
This is my first build that actually gets the CLI, the Tests and the Linter to all work. Please provide feedback and ideas for how to make it even more correct.
Also just a note: I am using Node 16.
For reasons unknown, on node 14 the CLI command works, but the Jest Test fails. I'd love to hear why if anyone knows.
Thanks for taking a look!
- Jason
The the original work of this boilerplate was done by metachris. I've left his original readme below.
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.
# 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 <filename>
yarn esbuild-browser
...- Take a look at all the scripts in
package.json - For publishing to npm, use
yarn 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
yarn esbuild-browser:dev
yarn esbuild-browser:watch
# Build the cli for node
yarn esbuild-node:dev
yarn esbuild-node:watchYou can generate a full clean build with yarn build-all (which uses both tsc and esbuild).
package.jsonincludesscriptsfor various esbuild commands: see hereesbuildhas a--global-name=xyzflag, 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 Jest tests like this:
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
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):
yarn docsThe 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: