Recently I ran across an issue with an NPM package in my TypeScript project; Property doesn't exist on type of object, the error said. The problem is that I knew it existed based on the developer docs for the package. Here is how I resolved this typing issue with the external package.
Why Your Types May Not Match
TypeScript type definition files help make third-party Javascript packages useful in our TypeScript code. They do that by providing information about existing variables, functions, and parameters in that package. Without definitions, our editor cannot provide us with suggestions or warn us of potential typing problems with our code. While many packages export their types, many do not and rely on Definitely Typed, an open-source repository of TypeScript type definitions, to provide this information. Definitely Typed is a great way to get types for packages. However, sometimes, the definitions are incomplete or incorrect, which leaves TypeScript with no way to enforce types. Luckily for us, we can provide our own definitions for the external package and can give back to the community to improve these types.
Updating TypeScript Type Definition Files
First, let’s update our project with the correct TypeScript types. Then, let’s look at how we can use our updated types to contribute to the Definitely Typed project.
Updating the Types in Your Project
The quickest way to correct the types for our project is to extend the existing definitions. Grab the already available definitions from Definitely Typed to jump-start the process. Create a new folder in your project called “types.” Then copy the whole folder from Definitely Typed for the package you are updating. The folder should include an index.d.ts, tsconfig.json, tslint.json, and test files. Now that we have the existing definitions in our project, we can update the types. An excellent resource for writing definition files is the TypeScript Declaration Files documentation.
Now that we’ve updated the types, let’s use them in our project. Add a package.json file to the package types folder. The package name should be named @types/<package-name>, and the npm init –scope types command will help scaffold the package.json. Add the types package as a dev dependency to your project, npm install <path-to-@types/<package> --save-dev.
Updating Definitely Typed
Now that you’ve updated your project with the appropriate types for the package, we can move our project forward. The updated definition files are helpful to others, so we can contribute those changes back to the community.
The easiest way to contribute is to fork the whole Definitely Typed repository on Github. This way, the entire repository can be pulled onto your local machine and you can make changes before creating a pull request. After pulling down the project, install NPM dependencies with npm install and bring your updated definition files into the project.
After updating the package from the ‘DefinitelyTyped’ folder, run the test for the updated package using npm run test <package-name>. This will check the declaration files and tell you about any issue you need to address, such as trailing whitespace or missing semicolons. After the tests for your package pass, running npm run test-all will verify that all other package declarations are in good standing.
Now commit the changes to your forked repository and create a pull request to merge your changes into the main repository. The typescript-bot will help you get your changes approved by another community member or a Definitely Typed maintainer. One of my favorite parts about contributing to this project was that the TypeScript bot links a playground for you to test your changes — really cool!
For reference, here is my contribution to the @types/mailchimp__mailchimp_marketing type definitions. Happy typing!