fuzzy-scrawl v1.0.4

TypeScript Boilerplate for 2021

This project uses esbuild to generate a browser compatible module.

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

# 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 (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).

# 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:

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 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 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

Development Notes

• live reloading
• live-server expects directory as path argument

Local Development

Although there are a number of ways to configure a local development (experience) server, doing so with Hot Reloading is a little more involved. This project uses--arguably--the path of least resistance: using esbuild in watch mode and live-server to serve up a root html document which has the compiled application code injected into it via a script tag.

• The influence for this arrangement came from here.
• In order to boot the development server up:

  yarn esbuild-browser:dev || npx yarn esbuild-browser:dev

• Some alternatives:

  • esbuild-dev-server: I didn't use this because it was as widely used.
  • helpful explanation of how to get Hot Reload working

Hot Reload

Hot Reload refreshes the local server. It does not dynamically refresh the local servers' modules (Hot Module Reloading, HMR).

Configuration

Using esbuild's (config) extensibility, I have added support for build-time post-CSS tooling (Sass).

HOW TO TROUBLESHOOT PLUGINS: https://github.com/zaydek/esbuild-watchfiles-bug

INITIAL ESBUILD SUPPORT FOR CSS MODULES + SCSS

The above is ridiculously helpful.

HOW IT CURRENTLY WORKS

• In separate terminals:
• Run npx live-server build to server index.html from build dir.
• Run npx yarn esbuild-browser:dev to watch files for Hot Reload.