如何编写和使用DefinitelyTyped上不存在的自定义声明文件？

Question

我使用的名为foo的npm包在DefinitelyTyped上不存在。换句话说，@types/foo不存在（或可能已过期！）

我仍然希望能够在noImplicitAny等更严格的设置下使用它，所以我需要自己编写自定义定义文件。最后我想向DefinitelyTyped发送一个pull请求，这样这个文件对我项目之外的其他人都有用。

有一些简单的解决方案，比如创建一个名为./src/types.d.ts的全局文件，我可以编写以下内容

declare module "foo" {
    export function hello(): void;
    export function world(): void;
}

但是，如果我使用该语法，当我将其提交给DefinitelyTyped时，我可能需要重写我的模块。

如何构建项目以便我可以轻松创作然后将本地.d.ts文件发送到DefinitelyTyped？

Answer 1

我将逐步解释这一点，这可能看起来很冗长，但按照给出的指示应该只需几分钟。实际上，这是您可以在bash或PowerShell中运行的简短版本！

mkdir -p ./local-types/foo
cd ./local-types/foo
npm init --scope types --yes
echo "export function hello(): void; export function world(): void" > ./index.d.ts
cd ../..
npm install ./local-types/foo

背景

让我们假设以下项目结构：

proj/
├─ tsconfig.json
└─ src/
   └─ ...

在项目的根目录下创建本地类型文件夹。

无论它叫什么，但我们称之为local-types。一旦掌握了我们在这里所做的事情，你就可以把它改成你想要的任何东西。

proj/
├─ tsconfig.json
├─ local-types/
└─ src/
   └─ ...

  

在本例之外的大多数情况下，我可能会将此命名为types。

在本地类型目录中创建一个新包

由于您尝试导入名为foo的模块，我们将创建一个名为foo的文件夹，其中包含index.d.ts。

// local-types/foo/index.d.ts

export function hello(): void;

export function world(): void;

我们还想通过创建package.json来使这个npm包：

cd local-types/foo
npm init --scope types --yes

此时，您的项目应如下所示：

proj/
├─ tsconfig.json
├─ local-types/
|  └─ foo/
|     └─ index.d.ts
|     └─ package.json
└─ src/
   └─ ...

您现在应该只能从foo中的任何文件导入src。

import { hello, world } from "foo";

hello();
world();

请注意，您可能没有index.d.ts的单入口点包。在这种情况下，您将需要模仿在npm上发布的包结构。

将包添加为依赖项（或可能是devDependency）

如果您正在编写库，那么您可能希望在依赖项中使用它，但应用程序可能希望使用devDependencies。只需添加file:./local-types/foo作为@types/foo的版本：

"dependencies": {
    "@types/foo": "file:local-types/foo"
}

发布到DefinitelyTyped

您的.d.ts文件是否完整且有用？考虑编写一些测试并向DefinitelyTyped发送拉取请求，以便其他人可以从您已完成的工作中受益！

如果您能够在运行时导入这些包没有问题，那么您已经拥有了相应的包结构。

要记住的事情

• 不要在任何这些本地类型的包中使用declare module "..."语法。
  • ...除非您正在尝试编写模块扩充。但你可能不是。
• 确保您的文件至少有一个import或export，除非它们是真正的脚本/全局文件。
• Follow advice given from the TypeScript website on authoring declaration files.