How to Change Type Definitions for an `@types/*` Package

Editing type definitions in the DefinitelyTyped repository can significantly enhance the TypeScript ecosystem. This guide provides a concise starting point for anyone looking to modify an existing type definition.

Before opening a new pull request (PR), please check if there is already a pending issue or PR that implements your changes. This helps avoid duplicate efforts and ensures a more streamlined review process. You can search for existing issues and PRs in the DefinitelyTyped repository to see if someone has already started working on the changes you intend to make. If a similar issue or PR exists, consider collaborating or providing feedback on the existing efforts.

Forking the Repository

First, fork the DefinitelyTyped repository by following the official guide.

Cloning Your Fork

Clone your fork of the DefinitelyTyped repository. Given the repository's size, use the --sparse and --filter options to perform a partial clone as described in the DefinitelyTyped README:

git clone --sparse --filter=blob:none https://github.com/<YOUR_USER_NAME>/DefinitelyTyped.git
cd DefinitelyTyped

This command clones only the files in the root directory. For more details, refer to the docs for git clone --sparse.

Adding Specific Types

Use the sparse-checkout command to add the specific types you need:

git sparse-checkout add types/<TYPE>
# For example, to edit the `@types/node` package:
git sparse-checkout add types/node

Check the package.json of your package (located at types/<TYPE>/package.json) for any dependent types specified under dependencies. If needed, add these dependencies using the sparse-checkout command:

git sparse-checkout add types/<DEPENDENCY_TYPE> types/<NEXT_DEPENDENCY_TYPE>

Installing Dependencies

Install the necessary dependencies using pnpm:

pnpm install

Editing Types

Edit the types in the types directory. Ensure you also update the corresponding tests. Once your edits are complete, run the tests:

pnpm test <TYPE>
# For the `@types/node` package:
pnpm test node

If the tests pass, format the code with dprint:

pnpm dprint fmt

Committing Your Changes

Create a new branch for your changes to keep your forked main branch in sync with the original DefinitelyTyped repository:

git checkout -b <BRANCH_NAME>
# Example:
git checkout -b fix-node-types

Add and commit your changes:

git add .
git commit -m "[@types/<TYPE>] <DESCRIPTION>"
# Example:
git commit -m "[@types/node] Add missing options to events.on"

Push your changes:

git push

Creating a Pull Request

Create a pull request to the DefinitelyTyped repository following the official guide.

Before submitting, edit the pull request template:

1. Follow the instructions for each checkbox in the first section and check them off by editing [ ] to [x].
2. Use the If changing an existing definition: section with Provide a URL to documentation or source code which provides context for the suggested changes: <<url here>> - make sure to actually provide an URL to documentation or source code that supports your changes.
3. If your changes include breaking changes for a new major version, update the version in the package.json.

Submit the pull request and wait for the maintainers to review your changes.

By following these steps, you can contribute effectively to the DefinitelyTyped repository, helping to maintain and improve type definitions for the TypeScript community.