typescript-starter

A typescript starter for building javascript libraries and projects

Build Status Codecov NPM version Standard Version dependencies Status devDependencies Status

typescript-starter

A typescript starter for building javascript libraries and projects:

  • Write standard, future javascript – with stable es7 features – today (stage 3 or finished features)
  • Optionally use typescript to improve tooling, linting, and documentation generation
  • Export as a javascript module, making your work fully tree-shakable for consumers using es6 imports (like Rollup or Webpack 2)
  • Export Typescript type declarations to improve your downstream development experience
  • Backwards compatibility for Node.js-style (CommonJS) imports
  • Both strict and flexible Typescript configurations available

So we can have nice things:

  • Generate API documentation (HTML or JSON) without a mess of JSDoc tags to maintain
  • Collocated, atomic, concurrent unit tests with AVA
  • Source-mapped code coverage reports with nyc
  • Configurable code coverage testing (for continuous integration)

Get started

Before you start, consider configuring or switching to an editor with good typescript support like vscode.

To see how this starter can be used, check out the examples folder.

Development zen

This starter includes a watch task which makes development faster and more interactive. It's particularly helpful for TDD/BDD workflows.

To start working, run:

$ yarn watch

which will build and watch the entire project for changes (to both the library source files and test source files). As you develop, you can add tests for new functionality – which will initially fail – before developing the new functionality. Each time you save, any changes will be rebuilt and retested.

Typescript builds on the left, tests run on the right:

typescript and AVA watch task

Since only changed files are rebuilt and retested, this workflow remains fast even for large projects.

Enable stronger type checking (recommended)

To make getting started easier, the default tsconfig.json is using the config/tsconfig.flexible configuration. This will allow you to get started without many warnings from Typescript.

To enable additional Typescript type checking features (a good idea for mission-critical or large projects), change the extends value in tsconfig.json to ./config/tsconfig.strict.

View test coverage

To generate and view test coverage, run:

$ yarn cov

This will create an HTML report of test coverage – source-mapped back to Typescript – and open it in your default browser.

source-mapped typescript test coverage example

Generate your API docs

The src folder is analyzed and documentation is automatically generated using typedoc.

$ yarn docs

This command generates API documentation for your library in HTML format.

Since types are tracked by Typescript, there's no need to indicate types in JSDoc format. For more information, see the typedoc documentation.

typedoc documentation example

For more advanced documentation generation, you can provide your own typedoc theme, or build your own documentation using the JSON typedoc export:

$ yarn docs:json

Generate/update changelog & release

This project is tooled for Conventional Changelog to make managing releases easier. See the standard-version documentation for more information on the workflow, or CHANGELOG.md for an example.

# bump package.json version, update CHANGELOG.md, git tag the release
$ yarn release
# Release without bumping package.json version
$ yarn release -- --first-release
# PGP sign the release
$ yarn release -- --sign

All package scripts

You can run the info script for information on each available package script.

$ yarn run info

info:
  Display information about the scripts
build:
  (Trash and re)build the library
lint:
  Lint all typescript source files
unit:
  Run unit tests
test:
  Lint and test the library
watch:
  Watch source files, rebuild library on changes, rerun relevant tests
watch:build:
  Watch source files, rebuild library on changes
watch:unit:
  Watch the build, rerun relevant tests on changes
cov:
  Run tests, generate the HTML coverage report, and open it in a browser
html-coverage:
  Output HTML test coverage report
send-coverage:
  Output lcov test coverage report and send it to codecov
docs:
  Generate API documentation and open it in a browser
docs:json:
  Generate API documentation in typedoc JSON format
release:
  Bump package.json version, update CHANGELOG.md, tag a release

Notes

Browser libraries

This starter currently does not run tests in a browser (AVA tests in Node exclusively). While the current testing system will be sufficient for most use cases, some projects will (also) need to implement a browser-based testing system like karma-ava. (Pull requests welcome!)

Dependency on tslib

By default, this project requires tslib as a dependency. This is the recommended way to use Typescript's es6 & es7 transpiling for sizable projects, but you can remove this dependency by removing the importHelpers compiler option in tsconfig.json. Depending on your usage, this may increase the size of your library significantly, as the Typescript compiler will inject it's helper functions directly into every file which uses them. (See also: noEmitHelpers)

Targeting older environments

By default, this library targets environments with native (or already-polyfilled) support for es6 features. If your library needs to target Internet Explorer, outdated Android browsers, or versions of Node older than v4, you may need to change the target in tsconfig.json to es5 (rather than es6) and bring in a Promise polyfill (such as es6-promise).

It's a good idea to maintain 100% unit test coverage, and always test in the environments you target.

Related Repositories

Ionic-TypeScript-Starter

Ionic-TypeScript-Starter

:iphone: Platform and IDE agnostic starter project for building mobile apps with ...

phaser-npm-webpack-typescript-starter-project

phaser-npm-webpack-typescript-starter-project

Project to get you started with your Phaser (using the npm module) game using Ty ...

react-redux-typescript-starter-kit

react-redux-typescript-starter-kit

Futuristic, bundle-free development environment for building Component-Driven SP ...

react-tsx-starter

react-tsx-starter

Isomorphic React TypeScript Starter Project ...

angular-webpack-material-lazyload-typescript-starter-template

angular-webpack-material-lazyload-typescript-starter-template

Angular starter template using typescript, angular-material, ui-router, oclazylo ...