TypeScript for Library Authors: Harnessing the Power of TypeScript for DX

Rate this content
Bookmark
The video discusses the advantages of using TypeScript for library authors, focusing on improving code quality, covering edge cases, and facilitating refactoring. TypeScript documentation is integrated into the code, providing up-to-date information directly in the IDE. Testing TypeScript types ensures accuracy, and tools like Unbuild and API Extractor are recommended. The importance of versioning types to avoid breaking user code is highlighted, and strategies for handling type changes are provided. The talk emphasizes using TypeScript for accurate function return values and leveraging type inference. Nuxt's use of TypeScript for automatic type detection in components and plugins is also covered.

From Author:

Using real-life open-source examples, we'll explore the power of TypeScript to improve your users' experience. We'll cover best practices for library authors, as well as tips and tricks for how to take a library to the next level. This talk will cover: 


- how to leverage the type inference to provide help to your users; 

- using types to reduce the need and complexity of your documentation - for example, using function overloads, string literal types, and helper (no-op) functions; 

- setting up testing to ensure your library works (and your types do too!) with tools like tsd and expect-type; 

- treating types as an API and reducing breaking changes whilst shipping enhancements; 

- I'd draw on my experience with libraries like nuxt3, sanity-typed-queries and typed-vuex and show what we managed to do and what I'd do differently in future. 

This talk has been presented at TypeScript Congress 2022, check out the latest edition of this JavaScript Conference.

FAQ

The speaker is Daniel Rowe, a member of the Nuxt core team based in the northeast of the UK. He maintains several open-source packages and has a strong interest in improving developer experience.

TypeScript helps improve code quality by covering edge cases, facilitating refactoring, and providing accurate documentation. It offers a true-to-life representation of how libraries work, enhancing the developer experience.

TypeScript types and TS doc (or JS doc) can serve as accurate, up-to-date documentation embedded directly in the code. This approach ensures users get the correct information for the version they are using without needing a separate documentation site.

Expect type and ts-expect-error are recommended for testing TypeScript types. These tools help ensure that the types are accurate and behave as expected.

Versioning TypeScript types is crucial because changes in types can break user code. Adhering to semantic versioning (semver) helps manage these changes and ensures users are aware of any potential breaking changes.

The 'fountain of truth' paradigm suggests allowing TypeScript to infer return types from the actual code, rather than manually declaring them. This approach helps ensure the types are accurate and reduces the risk of errors.

Types can be used to accurately describe the expected inputs and outputs of functions, enhancing the usability and reliability of the library. For example, using string literals instead of generic strings can provide more specific and useful information to the user.

Type inference allows TypeScript to deduce the types of variables and return values automatically. This feature is particularly useful for creating accurate and maintainable types, especially in complex libraries.

Nuxt uses TypeScript to provide automatic type detection for components, plugins, API routes, and more. This integration ensures that developers get accurate type information and support directly in their IDEs.

You can contact Daniel Rowe via email or Twitter for more information. He is also active on the Nuxt Discord server, where you can ping him directly with any questions.

Daniel Roe
Daniel Roe
25 min
29 Apr, 2022

Comments

Sign in or register to post your comment.

Video Transcription

1. Introduction to TypeScript for Library Authors

Short description:

TypeScript for library authors offers benefits for both internal and external use. Internally, it helps improve code quality, cover edge cases, and facilitate refactoring. Externally, it provides users with an accurate understanding of how libraries work, offering a true-to-life representation of their functionality. TypeScript allows users to gain insight into libraries and understand the expected behavior of function calls.

Hello. It's a pleasure to be here today, talking about TypeScript for library authors. It's dear to my heart because I'm self interested and love using libraries with great developer experience, and I'm sure you do as well.

My name is Daniel Rowe. I'm based in the northeast of the UK, and I'm on the Nuxt core team, and I maintain a few other open source packages as well. I should say in advance, this is my perspective as we dive into TypeScript for library authors, you may have other ideas. You may have better approaches, and I'd love to hear from you if that's the case. Please do contact me, either by email or Twitter is a great way to make contact. Please. I'd love to connect later.

So, to start with, the question I'd like to pose is what's the point of TypeScript for library authors, I guess. And obviously, even if you weren't exposing your types outside of your own project, I think there would still be benefit. I certainly would find that there would be myself. I think TypeScript helps improve the code that we produce. It helps us cover edge cases. It helps us see the possible alternatives and outcomes of what we're creating. And it helps with things like refactoring, making sure we haven't left something out. Lots of huge benefits for using TypeScript internally.

But I think looking at the question of why we use TypeScript for external benefit, the key reason is truth. And I think there are a couple of different implications for this that I hope to go through today. But I think it all comes back to truth. We're allowing our users a window into how our libraries work. That window is accurate. It needs to be accurate. We're offering them an alternative to looking at our source code or reading our documentation. Something that is actually a true-to-life representation of what is happening. And that I think is one of the things that makes TypeScript so amazing, when you're using it as you consume some other library. Because you're getting insight through it. Your IDE popup is telling you something about how it works under the hood. It's telling you something about what you can expect to come back from that function call.

2. Documentation and Examples in Code

Short description:

Types are part of your documentation. API documentation and examples should be in your code. Users get up-to-date information when using your library. No need for a separate website. You can add links, examples, default values, and version information. Mature standards like jsdoc provide a great way to see documentation in your IDE. You can even host it using tools like jsdocs.io or unpiped.

The possible options you can pass to it. That kind of thing. It's all about truth for me. And the first implication is documentation. That's about truth as well, isn't it? So types are part of your documentation or maybe even your documentation. Certainly, types and TS doc, JS doc, I'll use the terms interchangeably even though they're not exactly. But they can provide your library documentation.

So if you think of adding comments immediately before every function, every interface, every constant that you expose from your library, you can actually accurately describe that there. My hot take for today is all of your API documentation and examples should be in your code. It means that when your users are actually using your library, they get up to date, accurate information about the version that they are consuming at that moment in time. You don't have to have a fancy website with a drop down allowing users to select major versions, if your documentation is actually in the code itself. Their editor will surface the correct version for them. You can add links. You can add examples. You have the full power of markdown at your disposal. You can add default values. You can add the version something was introduced to the project at. Anything else that you might think or consider, jsdoc, they're really mature standards. And there's nothing quite that beats being able to see the documentation for what you're using in your IDE rather than having to go somewhere else or perform a quick search. You can even host it that way. Check out jsdocs.io. You can actually type any package in, and they'll render up documentation for you based on the declaration files for that project. You might even consider something like unpiped which is a package in the onjs.github organization which enables you to have a typed configuration schema. It might not be relevant for your project, we use it in Nuxt. We are able to type our configuration schema, and then that can be exported to json or to code. We can do things with it, such as generate documentation programmatically. That is what we use to ensure our Nuxt config documentation is accurate and updated on the website. It is always based on the actual code and the JSTOC in that code file.

Here is just a little example picked from a library I maintain. It is not complex, it is not difficult as an author to do this.