Javascript 用 Typescript 编写 NPM 模块

Writing NPM modules in Typescript

提问by Andreas Gassmann

I am working on my first NPM module. I briefly worked with typescript before and a big problem was that for many modules there were no definition files available. So I thought it would be a good idea to write my module in typescript.

我正在开发我的第一个 NPM 模块。我之前曾短暂地使用过打字稿，一个大问题是许多模块没有可用的定义文件。所以我认为用打字稿编写我的模块是个好主意。

However, I can't find any information on the best way to do that. I found this related question "Can I write npm package in coffeescript?" where people suggest only publishing the javascript files. But in contrast to the coffeescript files, the typescript files might actually be useful if they are used within a typescript application.

但是，我找不到有关执行此操作的最佳方法的任何信息。我发现了这个相关的问题“我可以在 coffeescript 中编写 npm 包吗？”人们建议只发布 javascript 文件。但与 coffeescript 文件相比，如果在 typescript 应用程序中使用 typescript 文件，它们实际上可能很有用。

Should I include Typescript files when publishing an NPM module, or should I only publish the javascript files and provide the generated .d.ts files to DefinitelyTyped?

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

采纳答案by basarat

Here is a sample Node module written in TypeScript : https://github.com/basarat/ts-npm-module

这是一个用 TypeScript 编写的示例节点模块：https: //github.com/basarat/ts-npm-module

Here is a sample TypeScript project that uses this sample module https://github.com/basarat/ts-npm-module-consume

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

Basically you need to :

基本上你需要：

• compile with commonjsand declaration:true
• generate a .d.tsfile

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

And then

进而

• Have your ide read the generated .d.ts.

• 让您的 ide 读取生成的.d.ts.

Atom-TypeScript just provides a nice workflow around this : https://github.com/TypeStrong/atom-typescript#packagejson-support

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

回答by bersling

With TypeScript 3.x or TypeScript 2.x, the following steps describe what you have to do to create a library (npm package) with TypeScript:

对于 TypeScript 3.x 或 TypeScript 2.x，以下步骤描述了使用 TypeScript 创建库（npm 包）所需执行的操作：

• Create your project as you normally would (with tests and everything)
• Add declaration: trueto tsconfig.jsonto generate typings.
• Export the API through an index.ts
• In the package.json, point to your generated typings. For example if your outDiris dist, then add "types": "dist/index.d.ts"to your package json.
• In the package.json, point to your main entry file. For example if your outDiris distand the main entry file is index.js, then add "main": "dist/index.js"to your package.json.
• Create an .npmignoreto ignore unnecessary files (e.g. the source).
• Publish to npm with npm publish. Use semver specifications for updates (patch / bug fix npm version patch, non-breaking additions npm version minor, breaking api changes npm version major)

• 像往常一样创建您的项目（包括测试和所有内容）
• 添加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 minorapi 更改npm version major）

Since it got me a while to sift through all the outdated resources on this topic on the internet (like the one on this page...) I decided to wrap it up in how-to-write-a-typescript-librarywith an up-to-date working minimal example.

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

回答by Varun Chatterji

This is a more recent answer using TypeScript 1.8.10:

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

My project structure is:

我的项目结构是：

|
|--- 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

I added the following in .npmignoreto avoid including extraneous files and keep the bare minimum to have the package imported and working:

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

node_modules/
*.log
*.tgz

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

My .gitignorehas:

我的.gitignore有：

typings

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

My package.jsonhas:

我的package.json有：

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

Now I run: npm pack

现在我运行： npm pack

The resultant file (when unzipped) has the following structure:

生成的文件（解压缩时）具有以下结构：

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

Now I go to the project where I want to use this as a library and type: npm install ./project-1.0.0.tgz

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

It successfully installs.

它安装成功。

Now I create a file index.tsin my project where I just installed the npm import Project = require("project");

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

Typing Project.gives me the Intellisense options which was the point of this whole exercise.

打字Project.给了我智能感知选项，这是整个练习的重点。

Hope this helps someone else in using their TypeScript npm projects as internal libraries in their bigger projects.

希望这有助于其他人在他们的大型项目中使用他们的 TypeScript npm 项目作为内部库。

PS:I believe that this approach of compiling projects to npm modules which can be used in other projects is reminiscent of the .dllin the .NETworld. I could well imagine projects being organised in a Solution in VS Code where each project produces a an npm package which can then be used in another project in the solution as a dependency.

PS：我相信这种将项目编译为可用于其他项目的npm模块的方法让人联想.dll到.NET世界上的。我可以想象在 VS Code 中的解决方案中组织项目，其中每个项目生成一个 npm 包，然后可以在解决方案中的另一个项目中作为依赖项使用。

Since it took a fair amount of time for me to figure this out, I have posted it in case someone is stuck here.

由于我花了相当长的时间才弄明白这一点，所以我把它贴出来以防有人卡在这里。

I also posted it for a closed bug at: https://github.com/npm/npm/issues/11546

我还在以下位置发布了一个已关闭的错误：https: //github.com/npm/npm/issues/11546

---

---

This example has been uploaded to Github: vchatterji/tsc-seed

这个例子已经上传到Github：vchatterji/tsc-seed

回答by Sven Efftinge

You should publish the original typescript sources instead of the type definition. In package.jsonlet the 'types' property point to the *.ts file.

您应该发布原始打字稿源而不是类型定义。在package.json让“类型”属性指向*的.ts文件。

*.d.tsare good to annotate existing JS libs, but as a consumer I'd rather read the typescript code than switching between type definitions and down-leveled, generated JS code.

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

回答by Tim

I mainly follow the suggestion by Varun Chatterji

我主要遵循Varun Chatterji的建议

But, I would like to show a complete example with unit testing and code coverage and publishing it into npmand importing them using javascriptor typescript

但是，我想展示一个带有单元测试和代码覆盖率的完整示例，npm并使用javascript或typescript

This module is written using typescript 2.2and it is important to configure the prepublishhook to compile the code using tscbefore publish it to npm

这个模块是使用编写的，在发布到 npm 之前typescript 2.2配置prepublish钩子来编译代码很重要tsc

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

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

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

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

回答by jjrv

You can use autodtsto handle distributing and using .d.tsfiles from npm also without support from the Atom IDE.

您也可以在没有 Atom IDE 支持的情况下使用autodts来处理分发和使用.d.ts来自 npm 的文件。

autodts generatewill bundle all your own .d.tsfiles together for publishing on npm, and autodts linkhandles references to other installed packages, which may not always be directly under node_modulesin a larger project split into several subpackages.

autodts generate将您自己的所有.d.ts文件捆绑在一起以在 npm 上发布，并autodts link处理对其他已安装包的引用，这些包可能并不总是直接node_modules在一个更大的项目中拆分成几个子包。

Both commands read their settings from package.jsonand tsconfig.jsonin "convention over configuration" style.

这两个命令读取它们的设置package.json，并tsconfig.json在“约定优于配置”的风格。

There's another answeron stackoverflow and a blog postwith more details.

stackoverflow 上还有另一个答案，还有一篇包含更多详细信息的博客文章。

回答by philkunz

At Lossless we created a one stop TypeScript dev tool for npm packages: https://gitzone.gitlab.io/npmts/

在 Lossless，我们为 npm 包创建了一个一站式 TypeScript 开发工具：https://gitzone.gitlab.io/npmts/