在Typescript中编写NPM模块

Question

我正在研究我的第一个NPM模块.我以前简单地使用过打字稿,但是一个很大的问题是,对于许多模块,没有可用的定义文件.所以我认为用打字稿写我的模块是个好主意.

但是,我找不到有关最佳方法的任何信息.我发现了这个相关问题" 我可以在coffeescript中编写npm包吗？ ",人们建议只发布javascript文件.但与coffeescript文件相比,如果在打字稿应用程序中使用打字稿文件,那么打字稿文件实际上可能很有用.

我应该在发布NPM模块时包含Typescript文件,还是应该只发布javascript文件并将生成的.d.ts文件提供给DefinitelyTyped？

Answer 1

以下是使用TypeScript编写的Node模块示例:https://github.com/basarat/ts-npm-module

下面是一个使用此示例模块的示例TypeScript项目https://github.com/basarat/ts-npm-module-consume

基本上你需要:

• 用commonjs和编译declaration:true
• 生成一个.d.ts文件

然后

• 你的ide读取生成的.d.ts.

Atom-TypeScript提供了一个很好的工作流程:https://github.com/TypeStrong/atom-typescript#packagejson-support

Answer 2

使用Typescript 2.x在2018年推荐的方式:

• 像往常一样创建项目(使用测试和所有内容)
• 添加declaration: true到tsconfig.json产生分型.
• 通过导出API index.ts
• 在package.json,指向您生成的输入.例如,如果outDir是dist,则添加"types": "dist/index.d.ts"到包json中.
• 在package.json,指向您的主条目文件.例如,如果你outDir是dist和主条目文件是index.js,那么添加"main": "dist/index.js"到你的package.json.
• 创建一个.npmignore忽略不必要的文件(例如源).
• 发布到npm npm publish.使用semver规范进行更新(补丁/错误修复npm version patch,非破坏性添加npm version minor,破坏api更改npm version major)

因为它让我一个同时通过所有过期的资源在互联网上关于这个主题(如一个在此页...)进行筛选,我决定把它包起来如何到写A-打字稿库与最新的工作最小的例子.

Answer 3

这是使用TypeScript 1.8.10的最新答案:

我的项目结构是:

|
|--- src
|--- test
|--- dist     <= My gulp file compiles and places the js, sourcemaps and .d.ts files here
|      |--- src
|      |--- test
|--- typings
.gitignore
.npmignore
gulpfile.js
package.json
README.md
tsconfig.json
tslint.json
typings.json

我添加了以下内容.npmignore以避免包含无关文件,并保持最低限度以使包导入和工作:

node_modules/
*.log
*.tgz

src/
test/
gulpfile.js
tsconfig.json
tslint.json
typings.json
typings
dist/test

我.gitignore有:

typings

# ignore .js.map files
*.js.map
*.js
dist

我package.json有:

"main": "dist/src/index.js",
"typings":  "dist/src/index.d.ts",

现在我跑: npm pack

生成的文件(解压缩时)具有以下结构:

|
|--- dist
|       |--- src
|              |
|              index.js
|              index.js.map
|              index.d.ts
|
package.json
README.md

现在我转到我想将其用作库并输入的项目: npm install ./project-1.0.0.tgz

它成功安装.

现在我index.ts在我刚刚安装了npm的项目中 创建了一个文件 import Project = require("project");

打字Project.给了我Intellisense选项,这是整个练习的重点.

希望这可以帮助其他人在他们更大的项目中使用他们的TypeScript npm项目作为内部库.

PS:我认为,编制项目NPM可以在其他项目中使用的模块的这种做法让人想起.dll在.NET世界各地.我可以想象在VS Code中的解决方案中组织项目,其中每个项目都生成一个npm包,然后可以在解决方案中的另一个项目中用作依赖项.

由于我花了相当多的时间来解决这个问题,所以我发布了以防万一有人被困在这里.

我还发布了一个已关闭的错误:https: //github.com/npm/npm/issues/11546

此示例已上传到Github:vchatterji/tsc-seed

Answer 4

您应该发布原始的typescript源而不是类型定义.在package.json让"类型"属性指向*的.ts文件.

*.d.ts 很好地注释现有的JS库,但作为消费者,我宁愿阅读打字稿代码而不是在类型定义和下层生成的JS代码之间切换.

Answer 5

我主要遵循Varun Chatterji的建议

但是,我想展示一个完整的单元测试和代码覆盖示例,npm并使用javascript或将其发布到并导入它们typescript

这个模块是使用编写的,在将代码发布到npm之前typescript 2.2配置prepublish钩子以编译代码非常重要tsc

https://github.com/sweetim/haversine-position

https://www.npmjs.com/package/haversine-position