一个用于构建javascript库和项目的typescript启动器:{#typescript-starter}
- 写标准的,未来的javascript - 具有稳定的es7功能 - 今天(stage 3或finished功能)
- 可以选择使用typescript来改进tooling,linting和文档生成
- 为消费者使用es6导入(如Rollup或Webpack 2),导出为一个JavaScript模块,使您的工作fully tree-shakable
- 导出类型声明,以提高您的下游开发经验
- Node.js风格(CommonJS)导入的向后兼容性
- 兼备严格和灵活两种可利用的typescript配置
因此我们可以拥有很棒的东西:
- 生成API文档(HTML或JSON),而没有一团糟的JSDoc标记来维护
- 用AVA进行并置,原子,并发单元测试
- 用nyc源代码覆盖率报告
- 可配置的代码覆盖测试(用于持续集成)
在开始之前,请考虑使用一个具有良好typescript支持的编辑器。
VS Code(以下)是一个受欢迎的选择。具有typscript支持的编辑器可以提供有用的自动完成、内嵌文档和代码重构功能。
要了解这个启动器如何用作其他项目的依赖关系,请查看示例文件夹。上面的例子来自examples/node-typescript
。
这个启动器包括一个监视任务,使开发更快,更具互动性。对TDD/BDD工作流程尤其有用。
要开始工作,安装Yarn并运行:
yarn watch
这将构建和监视整个项目的更改(对库源文件和测试源文件)。在开发新功能时,您可以为新功能添加测试-最初会失败-在开发新的功能之前。每次保存时,任何更改都将被重新生成并重新测试。
由于只有更改的文件被重建和重新测试,即使对于大型项目,此工作流仍然很快。
为了让开始更容易,默认的tsconfig.json
正在使用config/tsconfig.flexible
配置。这将允许您开始,而没有来自Typescript的任何警告。
要启用附加的Typescript类型检查功能(对关键任务或大型项目来说是个好主意),请将tsconfig.json
中的extend
值更改为./config/tsconfig.strict
。
要生成和查看测试覆盖率,请运行:
yarn cov
这将创建一个测试覆盖率的HTML报告 - 源映射回Typescript,并在默认浏览器中打开它。
使用typedoc,这个src文件夹被分析并且自动生成文档。
yarn docs
此命令以HTML格式为您的库生成API文档,并在浏览器中打开它。
由于类型由Typescript跟踪,因此不需要指定JSDoc格式的类型。有关更多信息,请参阅typedoc文档。
要生成并发布您的文档到GitHub Pages,请使用以下命令:
yarn docs:publish
一旦发布,对于您的仓库,您的文档应该在正确的GitHub页面URL中可用。 以这个仓库的GitHub页面为例。
对于更高级的文档生成,您可以提供自己的typedoc theme或构建您自己的文档使用JSON typedoc导出:
yarn docs:json
该项目用常规变更日志工具来使项目管理发布更容易。 有关工作流的更多信息请参阅标准版本文档,或一个相关例子的CHANGELOG.md
。
# bump package.json version, update CHANGELOG.md, git tag the release
yarn changelog
汇集上面的许多步骤,这个库包含一个一键发布命令。
# Standard release
yarn release
# Release without bumping package.json version
yarn changelog -- --first-release
# PGP sign the release
yarn changelog -- --sign
此命令运行如下命令:
yarn reset
: cleans the repo by removing all untracked files and resetting--hard
to the latest commit. (Note: this could be destructive.)yarn test
: build and fully test the projectyarn docs:publish
: generate and publish the latest version of the documentation to GitHub Pagesyarn changelog
: bump package.json version, update CHANGELOG.md, and git tag the release
当脚本完成后,它将记录推送发布提交到仓库的所需的最终命令,并在npm
注册处发布包:
git push --follow-tags origin master; npm publish
如果你想先查看发布,然后执行命令发布所有内容。
您可以运行info
脚本,以获取有关想要单独运行的每个脚本的信息。
yarn run info
info:
显示所有有关脚本的信息
build:
(垃圾回收)构建库
lint:
验证所有的typescript源文件的代码规范
unit:
构建库并运行单元测试
test:
代码规范验证,构建和测试库
watch:
监视源文件,重新构建库上的更改,重新运行相关测试
cov:
运行测试,生成HTML覆盖率报告,并在浏览器中打开它
docs:
生成HTML API文档并在浏览器中打开它
docs:publish:
生成HTML API文档并将其推送到GitHub Pages
docs:json:
以typedoc JSON格式生成API文档
release:
Bump package.json版本,更新CHANGELOG.md,标记一个版本
reset:
删除所有未跟踪的文件,并将仓库重置为最后一次提交
publish:
Reset, build, test, publish docs, and prepare release (一键发布过程)
typescript-starter
的src
被编译成三个单独的构建:main
,module
和browser
。main
构建是配置为使用CommonJS模块系统,而module
构建使用新的ES6模块系统。浏览器版本包含两个软件包,一个ES6模块(优先导出)和一个CommonJS软件包(主要用于测试)。
因为Node.js还不支持ES6模块系统,所以依赖于typescript-starter的Node.js项目将跟随package.json中的main
字段。支持新系统的工具(如Rollup)将跟随module
字段,使他们能够静态分析typescript-starter。当浏览器构建时,较新的工具将遵循browser
字段,这将解析为浏览器版本的ES6模块。
按照惯例,在typcript-starter中的测试与他们测试的文件是共存的。 该项目被配置为允许以Typescript编写测试,并且您的库被导入,就像被另一个项目一样使用。 (例如import { double, power } from 'typescript-starter'
)。这使得测试既直观又易于阅读,作为另一种形式的文档。
注意,测试是在标准的Node.js运行时(而不是像ts-node这样的替代方案)的最终版本中编译和执行的,以确保在该环境中通过测试。 如果在生产中使用ts-node,则可以修改此项目以跳过测试编译。
虽然浏览器和Node.js版本的库都已经过测试,但是这个启动程序当前没有在真正的浏览器中运行浏览器测试(AVA当前是仅用于Node)。虽然目前的测试系统对大多数用例都是足够的,但一些项目(也)需要实施基于浏览器的测试系统,如karma-ava。 (欢迎PR!)
注意:仅针对Node.js实现检查测试覆盖。这更简单,并且适用于node和浏览器实现具有不同依赖性的库,仅需较少的适配代码。只有几行差异(例如src/adapters/crypto.browser.ts
),包括测试覆盖率分析中的几行通常不是必需的。
此启动程序演示了当浏览器构建时导入和使用CommonJS模块(hash.js
),它的hash256
方法。 有关更多详细信息,请参阅build:browser-deps
package script和rollup.config.js。 当然,您的项目可能不需要此依赖关系,因此可以将其删除。如果您的库不需要为浏览器捆绑外部依赖项,还可以删除其他几个devDependencies(browserify
,rollup-plugin-alias
,rollup-plugin-commonjs
,rollup-plugin-node-resolve
等)。
默认情况下,此项目需要tslib作为依赖关系。这是为大型项目使用Typescript的es6和es7透明度的推荐方法,但您可以通过删除tsconfig.json
中的importHelpers
编译器选项来删除此依赖关系。 根据您的使用情况,这可能会显着增加您的库的大小,因为Typescript编译器将其辅助函数直接注入到使用它们的每个文件中。(另见:noEmitHelpers
→)
默认情况下,此库针对具有原生(或already-polyfilled)es6功能支持的环境。如果您的库目标是在Internet Explorer,过时的Android浏览器或V4以上版本的Node,则可能需要将tsconfig.json中的目标更改为es5(而不是es6),并导入Promise polyfill(如 es6-promise)。
保持100%的单元测试覆盖率是一个好主意,并且始终在您目标环境中进行测试。
您可以从使用typescript-starter
的项目中找到更多高级配置,使用示例并获取灵感。
- BitAuth – A universal identity and authentication protocol, based on bitcoin
- s6: Super Simple Secrets * Simple Secure Storage – An NPM library and tool to sprawl secrets with S3, ease, and encryption
使用typescript-starter
作为你的项目? 请PR将其添加到列表中!