- 
- 
- 
- 
- 
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 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 using an editor with good typescript support.
-VS Code (below) is a popular option. Editors with typescript support can provide helpful autocomplete, inline documentation, and code refactoring features.
-
- 
-
To see how this starter can be used as a dependency in other projects, check out the examples folder. The example above is from examples/node-typescript.
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, install Yarn and 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.
-
- 
-
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.
-
- 
-
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 and opens it in a browser.
-Since types are tracked by Typescript, there's no need to indicate types in JSDoc format. For more information, see the typedoc documentation.
-To generate and publish your documentation to GitHub Pages use the following command:
-yarn docs:publish
-Once published, your documentation should be available at the proper GitHub Pages URL for your repo. See this repo's GitHub Pages for an 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 & tag 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 changelog
-One-step publish preparation script
-Bringing together many of the steps above, this repo includes a one-step release command.
-# Standard release
-yarn release
-# Release without bumping package.json version
-yarn changelog -- --first-release
-# PGP sign the release
-yarn changelog -- --sign
-This command runs:
--
-
yarn reset: cleans the repo by removing all untracked files and resetting--hardto the latest commit. (Note: this could be destructive.)
- yarn test: build and fully test the project
- yarn docs:publish: generate and publish the latest version of the documentation to GitHub Pages
- yarn changelog: bump package.json version, update CHANGELOG.md, and git tag the release
-
When the script finishes, it will log the final command needed to push the release commit to the repo and publish the package on the npm registry:
git push --follow-tags origin master; npm publish
-Look over the release if you'd like, then execute the command to publish everything.
-All package scripts
-You can run the info script for information on each script intended to be individually run.
yarn run info
-
- info:
- Display information about the scripts
- build:
- (Trash and re)build the library
- lint:
- Lint all typescript source files
- unit:
- Build the library and run unit tests
- test:
- Lint, build, and test the library
- watch:
- Watch source files, rebuild library on changes, rerun relevant tests
- cov:
- Run tests, generate the HTML coverage report, and open it in a browser
- docs:
- Generate HTML API documentation and open it in a browser
- docs:publish:
- Generate HTML API documentation and push it to GitHub Pages
- docs:json:
- Generate API documentation in typedoc JSON format
- release:
- Bump package.json version, update CHANGELOG.md, tag a release
- reset:
- Delete all untracked files and reset the repo to the last commit
- publish:
- Reset, build, test, publish docs, and prepare release (a one-step publish process)
-Notes
-Multiple builds (main, module, and browser)
- The src of typescript-starter is compiled into three separate builds: main, module, and browser. The main build is configured to use the CommonJS module system, while the module build uses the new ES6 module system. The browser build contains two bundles, an ES6 module (the preferred export) and a CommonJS bundle (primarily used for testing).
Because Node.js does not yet support the ES6 module system, Node.js projects which depend on typescript-starter will follow the main field in package.json. Tools which support the new system (like Rollup) will follow the module field, giving them the ability to statically analyze typescript-starter. When building for the browser, newer tools follow the browser field, which will resolve to the browser build's ES6 module.
Testing
-By convention, tests in typescript-starter are co-located with the files they test. The project is configured to allow tests to be written in Typescript and your library to be imported as if it were being used by another project. (E.g. import { double, power } from 'typescript-starter'.) This makes tests both intuitive to write and easy to read as another form of documentation.
Note, tests are compiled and performed on the final builds in the standard Node.js runtime (rather than an alternative like ts-node) to ensure tests pass in that environment. If you are using ts-node in production, you can modify this project to skip test compilation.
-Browser libraries
-While both the browser and the Node.js versions of the library are tested, this starter currently does not run the browser tests in a real browser (AVA is currently Node-only). 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!)
-Note: test coverage is only checked against the Node.js implementation. This is much simpler, and works well for libraries where the node and browser implementations have different dependencies and only minor adapter code. With only a few lines of differences (e.g. src/adapters/crypto.browser.ts), including those few lines in test coverage analysis usually isn't necessary.
Building browser dependencies
-This starter demonstrates importing and using a CommonJS module (hash.js) for it's hash256 method when built for the browser. See the build:browser-deps package script and rollup.config.js for more details. Of course, your project likely does not need this dependency, so it can be removed. If your library doesn't need to bundle external dependencies for the browser, several other devDependencies can also be removed (browserify, rollup-plugin-alias, rollup-plugin-commonjs, rollup-plugin-node-resolve, etc).
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.
-Index
-Functions
-asyncABC
--
-
-
-
-
- -