Publishing a TypeScript declaration file on DefinitelyTyped

In my previous post, I showed you how to create a simple TypeScript declaration file. In this post, I will take that declaration file, and I will show you what you need to do to publish it to DefinitelyTyped.

In my previous post, I showed you how to create a simple TypeScript declaration file. In this post, I will take that declaration file, and I will show you what you need to do to publish it to DefinitelyTyped.

Publishing types

As already mentioned in the previous post, there are two ways to publish the declaration file we created. Either add the index.d.ts directly in the library or add the types in the DefinitelyTyped monorepo.
Since the greek-utils library does not belong to us, we have to go with the second option. However, if you are interested in the first option, you can take a look at this page of the TypeScript docs.

In the next section, we will explore how you can create a DefinitelyTyped package. After that, we will be able to install types through the types monorepo like:

npm i --save-dev @types/greek-utils

How to publish types on DefinitelyTyped

We will be following the contribution guide on the DefinitelyTyped repository, so in case you need a more detailed reference, feel free to check it out. Now let's jump into it!

Creating the types package

First of all, we have to fork the DefinitelyTyped repository.
We create a folder with the name of the library under the types directory. Then inside the types/greek-utils, you need to create four files:

A tslint.json, which is responsible for linting the declaration file. The linter is using dtslint which is a utility used to:

test a TypeScript declaration file for style and correctness. It will install typescript and tslint for you, so this is the only tool you need to test a type definition.
{
    "extends": "dtslint/dt.json"
}

What this line does is that it extends the dtslint file to use the configuration file for DefinitelyTyped.

Of course, we need to add the declaration file with the types we created under the name index.d.ts. Make sure you include the necessary headers in the comments. Otherwise, the linter will deny it. If you want more info on how to create it, check my previous post, or take a look in the docs on how to structure a declaration file and best practises. Below is the declaration file I created:

// Type definitions for greek-utils 1.2
// Project: https://github.com/vbarzokas/greek-utils
// Definitions by: Dimitris Kirtsios <https://github.com/dimkirt>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version X.X

export function sanitizeDiacritics(text: string, ignore?: string): string;

export function toGreek(text: string, ignore?: string): string;

export function toGreeklish(text: string, ignore?: string): string;

export function toPhoneticLatin(text: string, ignore?: string): string;

export function toTransliteratedLatin(text: string, ignore?: string): string;

Keep in mind that when you add your name in the Definitions header you become the maintainer of these types! Meaning you will receive notifications regarding issues with these types.

You only need to use the // TypeScript Version X.X header if you need to pin this type definition for a specific version of TypeScript and onwards.

Note: While I was preparing the pull request, I found out about dts-gen,a tool that generates a declaration scaffold for a library or a file. Feel free to check it out if you don't have a declaration file yet.

Then we need a file with the tests for the declaration file named greek-utils-tests.ts. These tests will not run, but they get typed checked so we can verify our types.

import * as greekUtils from 'greek-utils';

greekUtils.toGreek('pame re Paokara');
greekUtils.toGreeklish('πάμε ρε Παοκάρα');
greekUtils.toPhoneticLatin('PAOK');
greekUtils.toTransliteratedLatin('ksana');
greekUtils.sanitizeDiacritics('oxi');

Finally, we need a tsconfig.ts that will allow us to compile our package. The compilation will happen when using tsc within the package or as part of the linting job.

{
    "compilerOptions": {
        "noImplicitAny": true,
        "noImplicitThis": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true,
        "noEmit": true,
        "forceConsistentCasingInFileNames": true,
        "module": "commonjs",
        "lib": ["es5"],
        "baseUrl": "../",
        "typeRoots": ["../"],
        "types": []
    },

    "files": [
        "index.d.ts",
        "greek-utils-tests.ts"
    ]
}

Validating your package

To validate your declaration file against the standards of the project, you need to do the following:

Run npm i in the root of the repository.

Go to the directory of your package, in our case types/greek-utils, and run the linter.

npm run lint greek-utils

If you followed the post, you should not have any linting problems. However, if you face any issues most of the time, the linting errors are self-explanatory, so don't be afraid!

Then run npm test.

Finally, run prettier to ensure that you are following the DefinitelyTyped style guide.

npm run prettier -- --write types/greek-utils/**/*.ts

You are now ready to roll! When you open the pull request, you will see a checklist in the pull request template. Read it carefully. If you followed my instructions, it is quite likely that you already fulfill most of the checks.
Create the pull request and then wait for the pipeline to run to check your changes. A friendly bot will notify you about the status of your pull request. That was it! Now you wait until a maintainer reviews your request!

Summary

That's it for today! In this post, I showed how to publish a TypeScript declaration file on DefinitelyTyped. Let me know what you think about it in the comments below!

Stay tuned!

Subscribe to Backend Definite

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
jamie@example.com
Subscribe