502 lines
39 KiB
HTML
502 lines
39 KiB
HTML
<!doctype html>
|
||
<html class="default no-js">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||
<title>typescript-starter</title>
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<link rel="stylesheet" href="assets/css/main.css">
|
||
</head>
|
||
<body>
|
||
<header>
|
||
<div class="tsd-page-toolbar">
|
||
<div class="container">
|
||
<div class="table-wrap">
|
||
<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
|
||
<div class="field">
|
||
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
|
||
<input id="tsd-search-field" type="text" />
|
||
</div>
|
||
<ul class="results">
|
||
<li class="state loading">Preparing search index...</li>
|
||
<li class="state failure">The search index is not available</li>
|
||
</ul>
|
||
<a href="index.html" class="title">typescript-starter</a>
|
||
</div>
|
||
<div class="table-cell" id="tsd-widgets">
|
||
<div id="tsd-filter">
|
||
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
|
||
<div class="tsd-filter-group">
|
||
<div class="tsd-select" id="tsd-filter-visibility">
|
||
<span class="tsd-select-label">All</span>
|
||
<ul class="tsd-select-list">
|
||
<li data-value="public">Public</li>
|
||
<li data-value="protected">Public/Protected</li>
|
||
<li data-value="private" class="selected">All</li>
|
||
</ul>
|
||
</div>
|
||
<input type="checkbox" id="tsd-filter-inherited" checked />
|
||
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
|
||
<input type="checkbox" id="tsd-filter-externals" checked />
|
||
<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
|
||
<input type="checkbox" id="tsd-filter-only-exported" />
|
||
<label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label>
|
||
</div>
|
||
</div>
|
||
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="tsd-page-title">
|
||
<div class="container">
|
||
<ul class="tsd-breadcrumb">
|
||
<li>
|
||
<a href="globals.html">Globals</a>
|
||
</li>
|
||
</ul>
|
||
<h1> typescript-starter</h1>
|
||
</div>
|
||
</div>
|
||
</header>
|
||
<div class="container container-main">
|
||
<div class="row">
|
||
<div class="col-8 col-content">
|
||
<div class="tsd-panel tsd-typography">
|
||
<p><img height="0" width="0" alt="Typescript Starter Dark" src="https://cloud.githubusercontent.com/assets/904007/23006840/4e2b0c6c-f3d2-11e6-8f32-11384ee0cc4b.png"><img alt="typescript-starter" src="https://cloud.githubusercontent.com/assets/904007/23006836/4c67a3b8-f3d2-11e6-8784-12f0a34284d1.png"></p>
|
||
<p><a href="https://www.npmjs.com/package/typescript-starter"><img src="https://img.shields.io/npm/v/typescript-starter.svg" alt="NPM version"></a>
|
||
<a href="https://travis-ci.org/bitjson/typescript-starter"><img src="https://travis-ci.org/bitjson/typescript-starter.svg?branch=master" alt="Build Status"></a>
|
||
<a href="https://codecov.io/gh/bitjson/typescript-starter"><img src="https://img.shields.io/codecov/c/github/bitjson/typescript-starter.svg" alt="Codecov"></a>
|
||
<a href="https://github.com/conventional-changelog/standard-version"><img src="https://img.shields.io/badge/release-standard%20version-brightgreen.svg" alt="Standard Version"></a>
|
||
<a href="https://github.com/bitjson/typescript-starter"><img src="https://img.shields.io/github/stars/bitjson/typescript-starter.svg?style=social&logo=github&label=Stars" alt="GitHub stars"></a></p>
|
||
<h1 id="typescript-starter">typescript-starter</h1>
|
||
<h3 id="a-clean-simple-typescript-starter-for-building-javascript-libraries-and-node-js-applications-">A clean, simple <a href="https://www.typescriptlang.org/">typescript</a> starter for building javascript libraries and Node.js applications.</h3>
|
||
<p align="center">
|
||
<img alt="demo of the typescript-starter command-line interface" src="">
|
||
</p>
|
||
<h2 id="start-now">Start Now</h2>
|
||
<p>Run one simple command to install and use the interactive project generator. You'll need <a href="https://nodejs.org/">Node</a> <code>v8.9</code> (the current LTS release) or later.</p>
|
||
<pre><code class="lang-bash">npx typescript-starter
|
||
</code></pre>
|
||
<p>The interactive CLI will help you create and configure your project automatically.</p>
|
||
<blockquote>
|
||
<p>Since this repo includes <a href="./src/cli">the CLI and it's tests</a>, you'll only need to fork or clone this project if you want to contribute. If you find this project useful, please consider <a href="https://github.com/bitjson/typescript-starter/stargazers">leaving a star</a> so others can find it. Thanks!</p>
|
||
</blockquote>
|
||
<h1 id="features">Features</h1>
|
||
<ul>
|
||
<li>Write <strong>standard, future javascript</strong> – with stable ESNext features – today (<a href="https://github.com/tc39/proposals">stage 3</a> or <a href="https://github.com/tc39/proposals/blob/master/finished-proposals.md">finished</a> features)</li>
|
||
<li><a href="https://medium.freecodecamp.org/its-time-to-give-typescript-another-chance-2caaf7fabe61">Optionally use typescript</a> to improve tooling, linting, and documentation generation</li>
|
||
<li>Export as a <a href="http://jsmodules.io/">javascript module</a>, making your work <strong>fully tree-shakable</strong> for consumers capable of using <a href="https://github.com/rollup/rollup/wiki/pkg.module">es6 imports</a> (like <a href="http://rollupjs.org/">Rollup</a>, <a href="https://webpack.js.org/">Webpack</a>, or <a href="https://parceljs.org/">Parcel</a>)</li>
|
||
<li>Export type declarations to improve your downstream development experience</li>
|
||
<li>Backwards compatibility for Node.js-style (CommonJS) imports</li>
|
||
<li>Both strict and flexible <a href="config/tsconfig.json">typescript configurations</a> available</li>
|
||
</ul>
|
||
<p>So we can have nice things:</p>
|
||
<ul>
|
||
<li>Generate API documentation (HTML or JSON) <a href="https://blog.cloudflare.com/generating-documentation-for-typescript-projects/">without a mess of JSDoc tags</a> to maintain</li>
|
||
<li>Collocated, atomic, concurrent unit tests with <a href="https://github.com/avajs/ava">AVA</a></li>
|
||
<li>Source-mapped code coverage reports with <a href="https://github.com/istanbuljs/nyc">nyc</a></li>
|
||
<li>Configurable code coverage testing (for continuous integration)</li>
|
||
<li>Automatic linting and formatting using <a href="https://github.com/palantir/tslint">TSLint</a> and <a href="https://prettier.io/">Prettier</a></li>
|
||
<li>Automatically check for known vulnerabilities in your dependencies with <a href="https://github.com/nodesecurity/nsp"><code>nsp</code></a></li>
|
||
</ul>
|
||
<h2 id="but-first-a-good-editor">But first, a good editor</h2>
|
||
<p>Before you start, consider using an <a href="https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support">editor with good typescript support</a>.</p>
|
||
<p><a href="https://code.visualstudio.com/">VS Code</a> (below) is a popular option. Editors with typescript support can provide helpful autocomplete, inline documentation, and code refactoring features.</p>
|
||
<p>Also consider installing editor extensions for <a href="https://github.com/Microsoft/vscode-tslint">TSLint</a> and <a href="https://github.com/prettier/prettier-vscode">Prettier</a>. These extensions automatically format your code each time you save, and may quickly become invaluable.</p>
|
||
<p align="center">
|
||
<img alt="Typescript Editor Support – vscode" width="600" src="https://cloud.githubusercontent.com/assets/904007/23042221/ccebd534-f465-11e6-838d-e2449899282c.png">
|
||
</p>
|
||
<h1 id="developing-with-typescript-starter">Developing with typescript-starter</h1>
|
||
<h2 id="development-zen">Development zen</h2>
|
||
<p>To start working, run the <code>watch</code> task using <a href="https://docs.npmjs.com/getting-started/what-is-npm"><code>npm</code></a> or <a href="https://yarnpkg.com/"><code>yarn</code></a>.</p>
|
||
<pre><code class="lang-bash">npm run watch
|
||
</code></pre>
|
||
<p>This starter includes a watch task which makes development faster and more interactive. It's particularly helpful for <a href="https://en.wikipedia.org/wiki/Test-driven_development">TDD</a>/<a href="https://en.wikipedia.org/wiki/Behavior-driven_development">BDD</a> workflows.</p>
|
||
<p>The watch task 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.</p>
|
||
<p align="center">
|
||
<img alt="demo of typescript-starter's watch task" src="">
|
||
</p>
|
||
<p>Since only changed files are rebuilt and retested, this workflow remains fast even for large projects.</p>
|
||
<h2 id="enable-stronger-type-checking-recommended-">Enable stronger type checking (recommended)</h2>
|
||
<p>To make getting started easier, the default <code>tsconfig.json</code> is using a very flexible configuration. This will allow you to get started without many warnings from Typescript.</p>
|
||
<p>To enable additional Typescript type checking features (a good idea for mission-critical or large projects), review the commented-out lines in your <a href="./tsconfig.json">typescript compiler options</a>.</p>
|
||
<h2 id="view-test-coverage">View test coverage</h2>
|
||
<p>To generate and view test coverage, run:</p>
|
||
<pre><code class="lang-bash">npm run cov
|
||
</code></pre>
|
||
<p>This will create an HTML report of test coverage – source-mapped back to Typescript – and open it in your default browser.</p>
|
||
<p align="center">
|
||
<img height="600" alt="source-mapped typescript test coverage example" src="https://cloud.githubusercontent.com/assets/904007/22909301/5164c83a-f221-11e6-9d7c-72c924fde450.png">
|
||
</p>
|
||
<h2 id="generate-your-api-docs">Generate your API docs</h2>
|
||
<p>The src folder is analyzed and documentation is automatically generated using <a href="https://github.com/TypeStrong/typedoc">TypeDoc</a>.</p>
|
||
<pre><code class="lang-bash">npm run docs
|
||
</code></pre>
|
||
<p>This command generates API documentation for your library in HTML format and opens it in a browser.</p>
|
||
<p>Since types are tracked by Typescript, there's no need to indicate types in JSDoc format. For more information, see the <a href="http://typedoc.org/guides/doccomments/">TypeDoc documentation</a>.</p>
|
||
<p>To generate and publish your documentation to <a href="https://pages.github.com/">GitHub Pages</a> use the following command:</p>
|
||
<pre><code class="lang-bash">npm run docs:publish
|
||
</code></pre>
|
||
<p>Once published, your documentation should be available at the proper GitHub Pages URL for your repo. See <a href="https://bitjson.github.io/typescript-starter/"><code>typescript-starter</code>'s GitHub Pages</a> for an example.</p>
|
||
<p align="center">
|
||
<img height="500" alt="TypeDoc documentation example" src="https://cloud.githubusercontent.com/assets/904007/22909419/085b9e38-f222-11e6-996e-c7a86390478c.png">
|
||
</p>
|
||
<p>For more advanced documentation generation, you can provide your own <a href="http://typedoc.org/guides/themes/">TypeDoc theme</a>, or <a href="https://blog.cloudflare.com/generating-documentation-for-typescript-projects/">build your own documentation</a> using the JSON TypeDoc export:</p>
|
||
<pre><code class="lang-bash">npm run docs:json
|
||
</code></pre>
|
||
<h2 id="update-the-changelog-commit-tag-release">Update the changelog, commit, & tag release</h2>
|
||
<p>It's recommended that you install <a href="https://github.com/commitizen/cz-cli"><code>commitizen</code></a> to make commits to your project.</p>
|
||
<pre><code class="lang-bash">npm install -g commitizen
|
||
|
||
<span class="hljs-comment"># commit your changes:</span>
|
||
git cz
|
||
</code></pre>
|
||
<p>This project is tooled for <a href="https://github.com/conventional-changelog/conventional-changelog">conventional changelog</a> to make managing releases easier. See the <a href="https://github.com/conventional-changelog/standard-version">standard-version</a> documentation for more information on the workflow, or <a href="CHANGELOG.md"><code>CHANGELOG.md</code></a> for an example.</p>
|
||
<pre><code class="lang-bash"><span class="hljs-comment"># bump package.json version, update CHANGELOG.md, git tag the release</span>
|
||
npm run changelog
|
||
</code></pre>
|
||
<h2 id="one-step-publish-preparation-script">One-step publish preparation script</h2>
|
||
<p>Bringing together many of the steps above, this repo includes a one-step release preparation command.</p>
|
||
<pre><code class="lang-bash"><span class="hljs-comment"># Prepare a standard release:</span>
|
||
npm run prepare-release
|
||
</code></pre>
|
||
<p>You can also prepare a non-standard release:</p>
|
||
<pre><code class="lang-bash"><span class="hljs-comment"># Or a non-standard release:</span>
|
||
|
||
<span class="hljs-comment"># Build everything</span>
|
||
npm run all
|
||
|
||
<span class="hljs-comment"># Then version it</span>
|
||
npm run version -- --first-release <span class="hljs-comment"># don't bump package.json version</span>
|
||
npm run version -- --sign <span class="hljs-comment"># PGP sign it</span>
|
||
npm run version -- --prerelease alpha <span class="hljs-comment"># alpha release</span>
|
||
|
||
<span class="hljs-comment"># And don't forget to push the docs to GitHub pages:</span>
|
||
npm run docs:publish
|
||
</code></pre>
|
||
<p>This command runs the following tasks:</p>
|
||
<ul>
|
||
<li><code>reset</code>: cleans the repo by removing all untracked files and resetting <code>--hard</code> to the latest commit. (<strong>Note: this could be destructive.</strong>)</li>
|
||
<li><code>test</code>: build and fully test the project</li>
|
||
<li><code>docs:html</code>: generate the latest version of the documentation</li>
|
||
<li><code>docs:publish</code>: publish the documentation to GitHub Pages</li>
|
||
<li><code>changelog</code>: bump package.json version, update CHANGELOG.md, and git tag the release</li>
|
||
</ul>
|
||
<p>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 <code>npm</code> registry:</p>
|
||
<pre><code class="lang-bash">git push --follow-tags origin master; npm publish
|
||
</code></pre>
|
||
<p>Look over the release if you'd like, then execute the command to publish everything.</p>
|
||
<h2 id="get-scripts-info">Get scripts info</h2>
|
||
<p>You can run the <code>info</code> script for information on each script intended to be individually run.</p>
|
||
<pre><code>npm run info
|
||
|
||
> npm-scripts-info
|
||
|
||
info:
|
||
Display information about <span class="hljs-keyword">the</span> package scripts
|
||
build:
|
||
Clean <span class="hljs-keyword">and</span> rebuild <span class="hljs-keyword">the</span> project
|
||
fix:
|
||
Try <span class="hljs-built_in">to</span> automatically fix <span class="hljs-keyword">any</span> linting problems
|
||
test:
|
||
Lint <span class="hljs-keyword">and</span> unit test <span class="hljs-keyword">the</span> project
|
||
watch:
|
||
Watch <span class="hljs-keyword">and</span> rebuild <span class="hljs-keyword">the</span> project <span class="hljs-keyword">on</span> <span class="hljs-title">save</span>, <span class="hljs-title">then</span> <span class="hljs-title">rerun</span> <span class="hljs-title">relevant</span> <span class="hljs-title">tests</span>
|
||
cov:
|
||
Rebuild, run tests, <span class="hljs-keyword">then</span> <span class="hljs-built_in">create</span> <span class="hljs-keyword">and</span> <span class="hljs-built_in">open</span> <span class="hljs-keyword">the</span> coverage report
|
||
doc:
|
||
Generate HTML API documentation <span class="hljs-keyword">and</span> <span class="hljs-built_in">open</span> <span class="hljs-keyword">it</span> <span class="hljs-keyword">in</span> <span class="hljs-keyword">a</span> browser
|
||
doc:json:
|
||
Generate API documentation <span class="hljs-keyword">in</span> typedoc JSON <span class="hljs-built_in">format</span>
|
||
changelog:
|
||
Bump package.json <span class="hljs-built_in">version</span>, update CHANGELOG.md, tag release
|
||
reset:
|
||
Delete all untracked <span class="hljs-built_in">files</span> <span class="hljs-keyword">and</span> reset <span class="hljs-keyword">the</span> repo <span class="hljs-built_in">to</span> <span class="hljs-keyword">the</span> <span class="hljs-keyword">last</span> commit
|
||
release:
|
||
One-step: clean, build, test, publish docs, <span class="hljs-keyword">and</span> prep <span class="hljs-keyword">a</span> release
|
||
</code></pre><h1 id="faqs">FAQs</h1>
|
||
<h2 id="why-are-there-two-builds-main-and-module-">Why are there two builds? (<code>main</code> and <code>module</code>)</h2>
|
||
<p>The <code>src</code> of <code>typescript-starter</code> is compiled into two separate builds: <code>main</code> and <code>module</code>. The <code>main</code> build is <a href="https://github.com/bitjson/typescript-starter/blob/master/tsconfig.json#L8">configured to use the CommonJS module system</a>. The <code>module</code> build <a href="https://github.com/bitjson/typescript-starter/blob/master/config/tsconfig.module.json">uses the new es6 module system</a>.</p>
|
||
<p>Because Node.js LTS releases do not yet support the es6 module system, some projects which depend on your project will follow the <code>main</code> field in <a href="https://github.com/bitjson/typescript-starter/blob/master/package.json"><code>package.json</code></a>. Tools which support the new system (like <a href="https://github.com/rollup/rollup">Rollup</a>, <a href="https://webpack.js.org/">Webpack</a>, or <a href="https://parceljs.org/">Parcel</a>) will follow the <code>module</code> field, giving them the ability to statically analyze your project. These tools can tree-shake your <code>module</code> build to import only the code they need.</p>
|
||
<h2 id="why-put-tests-next-to-the-source-code-">Why put tests next to the source code?</h2>
|
||
<p>By convention, sample tests in this project are adjacent to the files they test.</p>
|
||
<ul>
|
||
<li>Such tests are easy to find.</li>
|
||
<li>You see at a glance if a part of your project lacks tests.</li>
|
||
<li>Nearby tests can reveal how a part works in context.</li>
|
||
<li>When you move the source (inevitable), you remember to move the test.</li>
|
||
<li>When you rename the source file (inevitable), you remember to rename the test file.</li>
|
||
</ul>
|
||
<p>(Bullet points taken from <a href="https://angular.io/guide/testing#q-spec-file-location">Angular's Testing Guide</a>.)</p>
|
||
<h2 id="can-i-move-the-tests-">Can I move the tests?</h2>
|
||
<p>Yes. For some projects, separating tests from the code they test may be desirable. This project is already configured to test any <code>*.spec.ts</code> files located in the <code>src</code> directory, so reorganize your tests however you'd like. You can put them all in a single folder, add tests that test more than one file, or mix and match strategies (e.g. for other types of tests, like integration or e2e tests).</p>
|
||
<h2 id="can-i-use-ts-node-for-all-the-things-">Can I use ts-node for all the things?</h2>
|
||
<p>Tests are compiled and performed on the final builds in the standard Node.js runtime (rather than an alternative like <a href="https://github.com/TypeStrong/ts-node">ts-node</a>) to ensure that they pass in that environment. If you are build a Node.js application, and you are using <a href="https://github.com/TypeStrong/ts-node/issues/104">ts-node in production</a>, you can modify this project to use <code>ts-node</code> rather than a <code>build</code> step.</p>
|
||
<p><strong>However, if you're building any kind of library, you should always compile to javascript.</strong></p>
|
||
<p>Library authors sometimes make the mistake of distributing their libraries in typescript. Intuitively, this seems like a reasonable course of action, especially if all of your intended consumers will be using typescript as well.</p>
|
||
<p>TypeScript has versions, and different versions of TypeScript may not be compatible. Upgrading to a new major version of TypeScript sometimes requires code changes, and must be done project-by-project. Additionally, if you're using the latest version of TypeScript to build your library, and one of your consumers is using an older version in their application, their compiler will be unable to compile your library.</p>
|
||
<h2 id="how-do-i-bundle-my-library-for-the-browser-">How do I bundle my library for the browser?</h2>
|
||
<p>The short answer is: <strong>don't pre-bundle your library</strong>.</p>
|
||
<p>Previous versions of <code>typescript-starter</code> included browser bundling using <a href="https://github.com/rollup/rollup">Rollup</a>. This feature has since been removed, since very few libraries should ever be pre-bundled.</p>
|
||
<p>If the consumer of your library is using Node.js, bundling is especially unnecessary, since Node.js can reliably resolve dependencies, and bundling may even make debugging more difficult.</p>
|
||
<p>If the consumer of your library is a browser application, <strong>the application likely has its own build tooling</strong>. Very few serious applications are manually bundling their javascript, especially with easy to use, no configuration tools like <a href="https://parceljs.org/">Parcel</a> available.</p>
|
||
<p>Your library is most useful to downstream consumers as a clean, modular codebase, properly exporting features using es6 exports. Consumers can import the exact es6 exports they need from your library, and tree-shake the rest.</p>
|
||
<h2 id="how-can-my-library-provide-different-functionality-between-node-js-and-the-browser-">How can my library provide different functionality between Node.js and the browser?</h2>
|
||
<p>In the past, complex javascript libraries have used solutions like <a href="http://browserify.org/">Browserify</a> to bundle a version of their application for the browser. Most of these solutions work by allowing library developers to extensively configure and manually override various dependencies with respective browser versions.</p>
|
||
<p>For example, where a Node.js application might use Node.js' built-in <a href="https://nodejs.org/api/crypto.html"><code>crypto</code> module</a>, a browser version would need to fall back to a polyfill-like alternative dependency like <a href="https://github.com/crypto-browserify/crypto-browserify"><code>crypto-browserify</code></a>.</p>
|
||
<p>With es6, this customization and configuration is no longer necessary. Your library can now export different functionality for different consumers. While browser consumers may import a native JavaScript crypto implementation which your library exports, Node.js users can choose to import a different, faster implementation which your library exports.</p>
|
||
<p>See <a href="./src/lib/hash.ts">hash.ts</a> for a complete example. Two different functions are exported, <code>sha256</code>, and <code>sha256Native</code>. Browser consumers will not be able to import <code>sha256Native</code>, since their bundler will be unable to resolve the built-in Node.js dependency (their bundler will throw an error). Node.js users, however, will be able to import it normally. Each consumer can import the exact functionality they need.</p>
|
||
<p>One perceived downside of this solution is that it complicates the library's API. Browser consumers will sometimes import one feature while Node.js users import another. While this argument has merit, we should weigh it against the benefits.</p>
|
||
<p>Providing a public API where consumer code is the same between browsers and Node.js is desirable, but it comes at the cost of significant configuration and complexity. In many cases, it requires that code be aware of its environment at runtime, requiring additional complexity and testing.</p>
|
||
<p>A better way to provide this developer experience is to provide similar APIs for each environment, and then encourage the use of es6 import aliasing to standardize between them.</p>
|
||
<p>For example, in the documentation for <code>typescript-starter</code>, we encourage Node.js users to import <code>sha256Native as sha256</code>. With this convention, we get a standard API without loaders or dependency substitution hacks.</p>
|
||
<pre><code class="lang-js"><span class="hljs-comment">// browser-application.js</span>
|
||
<span class="hljs-keyword">import</span> { sha256 } <span class="hljs-keyword">from</span> <span class="hljs-string">'typescript-starter'</span>;
|
||
|
||
<span class="hljs-comment">// fully-portable code</span>
|
||
<span class="hljs-built_in">console</span>.log(sha256(<span class="hljs-string">'test'</span>));
|
||
</code></pre>
|
||
<pre><code class="lang-js"><span class="hljs-comment">// node-application.js</span>
|
||
<span class="hljs-keyword">import</span> { sha256Native <span class="hljs-keyword">as</span> sha256 } <span class="hljs-keyword">from</span> <span class="hljs-string">'typescript-starter'</span>;
|
||
|
||
<span class="hljs-comment">// fully-portable code</span>
|
||
<span class="hljs-built_in">console</span>.log(sha256(<span class="hljs-string">'test'</span>));
|
||
</code></pre>
|
||
<h2 id="what-about-git-hooks-to-validate-commit-messages-">What about Git hooks to validate commit messages?</h2>
|
||
<p>This project uses <a href="https://github.com/conventional-changelog/standard-version">standard-version</a> to automatically update the changelog based on commit messages since the last release. To do this, each relevant commit must be properly formatted.</p>
|
||
<p>To ensure all commits follow the proper conventions, you can use a package like <a href="https://github.com/marionebl/commitlint">commitlint</a> with <a href="https://github.com/typicode/husky">Husky</a>. However, keep in mind that commit hooks can be confusing, especially for new contributors. They also interfere with some development tools and workflows.</p>
|
||
<p>If your project is private, or will primarily receive contributions from long-running contributors, this may be a good fit. Otherwise, this setup may raise the barrier to one-off contributions slightly.</p>
|
||
<p>Note, as a maintainer, if you manage your project on GitHub or a similar website, you can now use the <code>Squash and Merge</code> option to add a properly formatted, descriptive commit messages when merging each pull request. This is likely to be more valuable than trying to force one-time contributors to adhere to commit conventions, since you can also maintain a more consistent language style. Because this is the best choice for the vast majority of projects, <code>typescript-starter</code> does not bundle any commit message validation.</p>
|
||
<h1 id="contributing">Contributing</h1>
|
||
<p>To work on the CLI, clone and build the repo, then use <code>npm link</code> to install it globally.</p>
|
||
<pre><code>git <span class="hljs-built_in">clone</span> https://github.com/bitjson/typescript-starter.git
|
||
<span class="hljs-built_in">cd</span> typescript-starter
|
||
npm install
|
||
npm <span class="hljs-built_in">test</span>
|
||
npm link
|
||
</code></pre><p>To manually test the CLI, you can use the <code>TYPESCRIPT_STARTER_REPO_URL</code> environment variable to test a clone from your local repo. Run <code>npm run watch</code> as you're developing, then in a different testing directory:</p>
|
||
<pre><code><span class="hljs-built_in">mkdir</span> typescript-starter-testing
|
||
<span class="hljs-built_in">cd</span> typescript-starter-testing
|
||
TYPESCRIPT_STARTER_REPO_URL='/local/<span class="hljs-built_in">path</span>/to/typescript-starter' typescript-starter
|
||
</code></pre><p>You can also <code>TYPESCRIPT_STARTER_REPO_URL</code> to any valid Git URL, such as your fork of this repo:</p>
|
||
<pre><code><span class="hljs-attr">TYPESCRIPT_STARTER_REPO_URL</span>=<span class="hljs-string">'https://github.com/YOUR_USERNAME/typescript-starter.git'</span> typescript-starter
|
||
</code></pre><p>If you're using <a href="https://code.visualstudio.com/">VS Code</a>, the <code>Debug CLI</code> launch configuration also allows you to immediately build and step through execution of the CLI.</p>
|
||
<h1 id="in-the-wild">In the wild</h1>
|
||
<p>You can find more advanced configurations, usage examples, and inspiration from other projects using <code>typescript-starter</code>:</p>
|
||
<ul>
|
||
<li><a href="https://github.com/bitauth/">BitAuth</a> – A universal identity and authentication protocol, based on bitcoin</li>
|
||
<li><a href="https://gitlab.com/td7x/s6/">s6: Super Simple Secrets * Simple Secure Storage</a> – An NPM library and tool to sprawl secrets with S3, ease, and encryption</li>
|
||
</ul>
|
||
<p>Using <code>typescript-starter</code> for your project? Please send a pull request to add it to the list!</p>
|
||
</div>
|
||
</div>
|
||
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
|
||
<nav class="tsd-navigation primary">
|
||
<ul>
|
||
<li class="globals ">
|
||
<a href="globals.html"><em>Globals</em></a>
|
||
</li>
|
||
</ul>
|
||
</nav>
|
||
<nav class="tsd-navigation secondary menu-sticky">
|
||
<ul class="before-current">
|
||
<li class=" tsd-kind-enum">
|
||
<a href="enums/placeholders.html" class="tsd-kind-icon">Placeholders</a>
|
||
</li>
|
||
<li class=" tsd-kind-enum">
|
||
<a href="enums/runner.html" class="tsd-kind-icon">Runner</a>
|
||
</li>
|
||
<li class=" tsd-kind-enum tsd-is-not-exported">
|
||
<a href="enums/testdirectories.html" class="tsd-kind-icon">Test<wbr>Directories</a>
|
||
</li>
|
||
<li class=" tsd-kind-interface">
|
||
<a href="interfaces/tasks.html" class="tsd-kind-icon">Tasks</a>
|
||
</li>
|
||
<li class=" tsd-kind-interface">
|
||
<a href="interfaces/typescriptstarterinferredoptions.html" class="tsd-kind-icon">Typescript<wbr>Starter<wbr>Inferred<wbr>Options</a>
|
||
</li>
|
||
<li class=" tsd-kind-interface">
|
||
<a href="interfaces/typescriptstarteroptions.html" class="tsd-kind-icon">Typescript<wbr>Starter<wbr>Options</a>
|
||
</li>
|
||
<li class=" tsd-kind-interface">
|
||
<a href="interfaces/typescriptstarteruseroptions.html" class="tsd-kind-icon">Typescript<wbr>Starter<wbr>User<wbr>Options</a>
|
||
</li>
|
||
<li class=" tsd-kind-variable tsd-is-not-exported">
|
||
<a href="globals.html#builddir" class="tsd-kind-icon">build<wbr>Dir</a>
|
||
</li>
|
||
<li class=" tsd-kind-variable tsd-is-not-exported">
|
||
<a href="globals.html#down" class="tsd-kind-icon">down</a>
|
||
</li>
|
||
<li class=" tsd-kind-variable tsd-is-not-exported">
|
||
<a href="globals.html#enter" class="tsd-kind-icon">enter</a>
|
||
</li>
|
||
<li class=" tsd-kind-variable tsd-is-not-exported">
|
||
<a href="globals.html#inherit" class="tsd-kind-icon">inherit</a>
|
||
</li>
|
||
<li class=" tsd-kind-variable tsd-is-not-exported">
|
||
<a href="globals.html#repourl" class="tsd-kind-icon">repoURL</a>
|
||
</li>
|
||
<li class=" tsd-kind-variable tsd-is-not-exported">
|
||
<a href="globals.html#up" class="tsd-kind-icon">up</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#asyncabc" class="tsd-kind-icon">asyncABC</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#checkargs" class="tsd-kind-icon">check<wbr>Args</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#clonerepo" class="tsd-kind-icon">clone<wbr>Repo</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#double" class="tsd-kind-icon">double</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#getgithubusername" class="tsd-kind-icon">get<wbr>Github<wbr>Username</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#getinferredoptions" class="tsd-kind-icon">get<wbr>Inferred<wbr>Options</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#getintro" class="tsd-kind-icon">get<wbr>Intro</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#getrepourl" class="tsd-kind-icon">get<wbr>Repo<wbr>Url</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#getuserinfo" class="tsd-kind-icon">get<wbr>User<wbr>Info</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#hash" class="tsd-kind-icon">hash</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#hashallthethings" class="tsd-kind-icon">hash<wbr>All<wbr>The<wbr>Things</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#initialcommit" class="tsd-kind-icon">initial<wbr>Commit</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#inquire" class="tsd-kind-icon">inquire</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#install" class="tsd-kind-icon">install</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#mockerr" class="tsd-kind-icon">mock<wbr>Err</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#ms" class="tsd-kind-icon">ms</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#passupdatenotifier" class="tsd-kind-icon">pass<wbr>Update<wbr>Notifier</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#power" class="tsd-kind-icon">power</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#readpackagejson" class="tsd-kind-icon">read<wbr>Package<wbr>Json</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#sandboxtasks" class="tsd-kind-icon">sandbox<wbr>Tasks</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#sha256" class="tsd-kind-icon">sha256</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#sha256native" class="tsd-kind-icon">sha256<wbr>Native</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#silenceconsole" class="tsd-kind-icon">silence<wbr>Console</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#testinteractive" class="tsd-kind-icon">test<wbr>Interactive</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#typescriptstarter" class="tsd-kind-icon">typescript<wbr>Starter</a>
|
||
</li>
|
||
<li class=" tsd-kind-function">
|
||
<a href="globals.html#validatename" class="tsd-kind-icon">validate<wbr>Name</a>
|
||
</li>
|
||
<li class=" tsd-kind-function tsd-is-not-exported">
|
||
<a href="globals.html#writepackagejson" class="tsd-kind-icon">write<wbr>Package<wbr>Json</a>
|
||
</li>
|
||
<li class=" tsd-kind-object-literal">
|
||
<a href="globals.html#livetasks" class="tsd-kind-icon">Live<wbr>Tasks</a>
|
||
</li>
|
||
<li class=" tsd-kind-object-literal tsd-is-not-exported">
|
||
<a href="globals.html#sandboxoptions" class="tsd-kind-icon">sandbox<wbr>Options</a>
|
||
</li>
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<footer class="with-border-bottom">
|
||
<div class="container">
|
||
<h2>Legend</h2>
|
||
<div class="tsd-legend-group">
|
||
<ul class="tsd-legend">
|
||
<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
|
||
<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
|
||
<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
|
||
<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
|
||
<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
|
||
<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
|
||
<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
|
||
</ul>
|
||
<ul class="tsd-legend">
|
||
<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
|
||
<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
|
||
<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
|
||
<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
|
||
</ul>
|
||
<ul class="tsd-legend">
|
||
<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
|
||
<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
|
||
<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
|
||
<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
|
||
<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
|
||
<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
|
||
</ul>
|
||
<ul class="tsd-legend">
|
||
<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
|
||
<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
|
||
<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
|
||
<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
|
||
<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
|
||
<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
|
||
<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
|
||
</ul>
|
||
<ul class="tsd-legend">
|
||
<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
|
||
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
|
||
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
|
||
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
|
||
</ul>
|
||
<ul class="tsd-legend">
|
||
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
|
||
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
|
||
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
|
||
</ul>
|
||
<ul class="tsd-legend">
|
||
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
|
||
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
|
||
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
|
||
</ul>
|
||
<ul class="tsd-legend">
|
||
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
|
||
<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
<div class="container tsd-generator">
|
||
<p>Generated using <a href="http://typedoc.org/" target="_blank">TypeDoc</a></p>
|
||
</div>
|
||
<div class="overlay"></div>
|
||
<script src="assets/js/main.js"></script>
|
||
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
|
||
</body>
|
||
</html> |