How to add a typescript definition file to a npm package?

Adding TypeScript declaration files (.d.ts files) to an npm package enables developers using the package to benefit from type checking and code completion in TypeScript projects. The following are the steps to add TypeScript declaration files to an npm package:

Step 1: Create TypeScript Declaration Files

First, create corresponding TypeScript declaration files for the JavaScript code in your package. These files typically have the extension .d.ts. For example, if your package has a main file named index.js, create a declaration file named index.d.ts that contains type declarations for all exported functions or objects.

typescript
// index.d.ts
export function add(a: number, b: number): number;

Step 2: Configure package.json

In the package.json file, specify the location of the TypeScript declaration files. This is typically done using the types or typings field:

json
{
  "name": "your-package-name",
  "version": "1.0.0",
  "main": "index.js",
  "types": "index.d.ts"
}

In this example, the types field informs the TypeScript compiler and development tools about the location of your declaration files.

Step 3: Publish to npm

Ensure your declaration files (index.d.ts) and package.json are included in the files you publish to npm. This is typically achieved by confirming they are not excluded by the .npmignore file or by explicitly listing them in the files field of package.json:

json
{
  "files": [
    "index.js",
    "index.d.ts"
  ]
}

Step 4: Test Your Type Declarations

Before publishing your package, verify your type declarations work correctly in a TypeScript project. Achieve this by linking your package to a test project. Use npm link to create a local link and install it in the test project:

bash
# In your package directory
npm link

# In the test project directory
npm link your-package-name

Then, attempt to use your package in the test project to check for type errors and confirm the editor provides appropriate code completion.

Summary

By following these steps, you can add TypeScript declaration files to your npm package, enhancing development experience and type safety. This is particularly important for maintaining high-quality open-source projects, as it helps other developers understand and use your package more effectively.