How TypeScript is integrated in your editor

Rate this content
Bookmark

How can an editor ""automagically"" show type errors when you create a single TypeScript file without running ""npm install typescript"" or having a tsconfig.json file? Is a completion list build by your coding editor, TypeScript itself, or some other mysterious being? What is TSServer?
In this talk I will give you an overview of how the TypeScript server communicates with IDEs and other editors, delivering rich language features without ever running tsc.

Maria Solano
Maria Solano
18 min
21 Sep, 2023

Comments

Sign in or register to post your comment.

Video Summary and Transcription

Today's Talk explores TypeScript integration and refactoring, code action handling, the TypeScript server and refactoring process, bug reporting, and the TypeScript protocol and LSP. The Talk discusses how TypeScript is integrated into editors, the role of code action providers, and the communication between the client and server. It also highlights the two-stage process of code actions and the importance of bug reporting. Additionally, it mentions the TypeScript protocol and how it allows for language-specific extensions. LSP is mentioned as a powerful extensibility solution used by various languages.

Available in Español

1. TypeScript Integration and Refactoring

Short description:

Hello, everyone! Today we'll explore how TypeScript is integrated into your editor, and who does what, and when. We'll use TypeScript inline variable refactor as an example. A code action is tied to a diagnostic, representing something that you can do to potentially fix errors. Refactoring provides smart recommendations for writing cleaner or nicer code. The editor recognizes trigger events, which can be passive or explicit. TypeScript shows refactorings based on trigger kind, and you can explicitly request a refactor for variables.

Hello, everyone, and thank you for joining me today. I'm Maria Solano, and I'm a software engineer at Microsoft. Quickly introducing myself, I focus on TypeScript editor tooling, but sometimes I also dive into LSP extensibility, Visual Studio's JavaScript Project System, or I just stare at the title TypeScript checker for a couple of hours, trying to absorb its wisdom, as I'm sure all of you have done.

Today we'll explore how TypeScript is integrated into your editor, and who does what, and when. For this, we'll use TypeScript inline variable refactor as an example, which is my favorite, mainly because I implemented it. Say that you have this print greeting function, and your cursor is in the first line of its body. In an editor like VS Code, you'll see a lightbulb. Where is that lightbulb coming from? Spoiler alert, if you click on it, a list appears. Who constructs a list and how are items inserted into that list? Not only VS Code has this functionality, Visual Studio, NeoVim, Emacs, Zed, and other obscure editors also have a TypeScript lightbulb experience that doesn't differ much from the one in VS Code. How is that done?

As a side note, during this talk I'll be using code action and refactoring as synonyms, despite that they're not exactly the same. Although the difference is a technicality, I'll explain it anyway just so that you can understand when your next code editor trivia game. A code action is tied to a diagnostic, and hence represents something that you can do to potentially fix those errors. Refactoring, on the other hand, aren't corrections, they're just smart recommendations for writing cleaner or nicer code, but it doesn't mean that there's something wrong with what you wrote.

Going back to PrintGreeting, the first thing that happens is that the editor will recognize a trigger event. This can be a passive action, such as your cursor being placed in a position where a refactoring could be applied. The trigger could also be explicit, such as one that you configure with a keybinding. Note that results could differ based on the trigger kind. Having a constant lightbulb popping up everywhere on your screen could be annoying, and so TypeScript might decide to show you certain refactorings only if you really want to see them. In this example, TypeScript will show a lightbulb besides the identifier of a variable that could be inlined, but you'll need to explicitly request the refactor in references of such variables.

2. Code Action Handling and Providers

Short description:

The editor needs someone who can understand the code to determine which refactorings to display. It records the position and content type, which may not directly correspond to the file extension. Extensions can handle code action requests using different mechanisms, such as registering a callback. Multiple code action providers can enhance the fixes provided by the language server.

Now say that we are no-beam gurus and use the mouse to click on the lightbulb. The editor doesn't actually know which refactorings to display here. It needs someone who can understand the code.

To communicate with that someone, the editor will record the position as well as the content type. Note that the content type isn't exactly a 1-to-1 mapping with the type coming from the file extension. A TypeScript snippet inside a script block of an HTML file is also assigned to the TypeScript content type. This is how you can still get code action, completions and the correct syntax highlighting in embedded code.

An extension announces that it can handle the code action request. There are different mechanisms to do so. In VS Code, you would register a code action provider for the TypeScript content type. In Visual Studio, you could use Roslyn APIs or the language service protocol. Most of the time, this basically involves registering a callback and telling the editor when to invoke it. Note that this is unlimited to language servers. Extensions like ESLint can also hook up into the code action list to enhance the fixes provided by the language server. This also means that there can be multiple code action providers coming from different extensions. The editor will then combine all of the results into a single list.

3. TypeScript Server and Refactoring Process

Short description:

TS-Server is the JavaScript and TypeScript language server that encapsulates the language compiler and other features using a JSON protocol. Editors provide the same TypeScript experience by following this protocol. TSC shows errors preventing successful TypeScript compilation, while other features focus on the editing experience. The editor translates position and file information into a format understood by TS-Server. The communication between the client and server is managed in session.ts, which handles commands, language services, and project tracking. The getApplicableRefactors function delegates requests to the assigned service, ensuring code modifications align with preferences. The inline variable refactoring checks for variable initialization, code stability, and references before performing the modification.

But OK, I'll back off now because I already mentioned the TypeScript server before properly introducing it. As the name suggests, TS-Server is the JavaScript and TypeScript language server, an executable which encapsulates the language compiler together with other features that are represented with a JSON protocol. This protocol defines a set of commands which represent each message you can send to TS-Server together with the request and response format. This is how different editors can provide the same TypeScript experience, they are all just following the same protocol.

For example, when sending a completion request with a completion request payload, you'll get a completion response back. When I first joined this team I remember being confused with the difference between TS-Server and the TypeScript compiler. TSC can indeed show you TypeScript errors, but these are only the ones that prevented successful TypeScript compilation. Other features revolve around the editing experience. Think of how it doesn't make sense to figure out refactors if you're just transpiling to javascript code.

Before returning to the event handling, remember that the editor just had the position and file information, and so first it needs to translate that into something the TS-Server understands. Here I show a simplified snippet of what the TypeScript VS Code extension does, but Visual Studio has a basically identical C-Sharp implementation of the same logic. About that first line of the arguments, that's because VS Code uses zero-based lines and columns, but TypeScript requires 1-based positions for these. You can imagine the off-by-one errors we've had because of that. You might also wonder, where is that client variable coming from? In this context we use client and editor interchangeably. Since TypeScript is the server, the client is whatever is sending messages on the other side. TS server is listening on the other side, and the state and delegation of this communication is mostly encapsulated in session.ts. In this file, there's a handler for each command defined in the protocol, delegating to each language service and performing some processing of the arguments and responses before putting them back on the wire. Here we also keep track of the TypeScript project, which is defined by your tsconfig.json file or by performing some discovery heuristics in the case that you have a set of TypeScript files in a random folder. It's up to this layer to pick up the results from one project, or combine them across multiple ones.

Moving on to the session handler of interest, we arrive to the getApplicableRefactors function. Here we extract each argument, get the project, and then delegate to the assigned service for that request. Notice the getPreferences call. Since refactorings can change your code, we try to ensure that the applied modifications have the indentation, code type and other style needs that you have configured. Each refactoring has its own handler and the one for inline variable does something like this. Given the arguments from the request, it will ask the type checker for their respective typescript node. And by the way, if you want to learn more about typescript's inner workings, you might have fun looking at that 50,000 line long beast. It then performs a bunch of checks to make sure that such a node corresponds to a variable initialized to a value. It also tries to ensure that your code doesn't break when applying the refactor, and so we check that you are not exporting the variable, among other obscure verifications that my more knowledgeable peers told me to consider. After that, we piggyback on findAllReferences to find all the references we would need to modify. Next we ensure that all references' locations could correctly handle the value replacement.

4. Refactoring Process and Bug Reporting

Short description:

And if any of these checks fail, we just return on defy to indicate that the refactor cannot be applied here. The response is then sent back to the editor, which performs an analogous translation to add those refactorings to the lightbulb list. The editor now unfolded the code action list and showed the user how they could improve their code. They picked the best action ever, of inline variable, and we sent another request to tserver. Code actions are an example of a tserver command that happens in two stages. In getApplicableRefactors we just notified the editors which refactors could be applied, but we didn't tell it how. Refactorings might seem special here. But there are other operations with two steps that you've used a lot already. Completions are another example. Let's go back to the handler for this refactor. When asked to apply the action, it will again ask the compiler for the node that's being inline, the references to it, as well as the expression we'll replace the variable with. It then updates all the references to use the value instead of the variable identifier. And finally, it gets rid of the now on use variable. After the editor reads and translates the response, the refactor is finally applied. Now that you're TS Server experts, impress editor and TypeScript maintainers the next time you encounter a bug and create a GitHub issue. Say that when applying the code action, the modified line is off by one. Without further context, this is a language server bug. Also, if it's a server bug you would be able to reproduce the issue in another editor. As another scenario, say that when clicking on the light bulb, the displayed list has duplicate items. This is an editor bug. If you really want to look like a professional, you can even take a look at the TS server logs, or by setting TypeScript trace level to verbose in VS Code, to see what exactly the server is receiving and returning. That will help pinpoint where things go downhill.

And if any of these checks fail, we just return on defy to indicate that the refactor cannot be applied here. The response is then sent back to the editor, which performs an analogous translation to add those refactorings to the lightbulb list.

And fantastic! The editor now unfolded the code action list and showed the user how they could improve their code. They picked the best action ever, of inline variable, and we sent another request to tserver.

At this point you might be wondering, why do we need to talk to tserver again? This is because code actions are an example of a tserver command that happens in two stages. In getApplicableRefactors we just notified the editors which refactors could be applied, but we didn't tell it how. This is because we don't want to compute all the necessary file modifications for refactorings if you won't even click on them. Only when the refactoring is actually selected, the editor will ask tsserver to apply the chosen item.

Refactorings might seem special here. But there are other operations with two steps that you've used a lot already. Completions are another example, you might have a completion item with an exported object from another file. If selected, not only the completed line will be modified, TypeScript will also update your imports to make sure the new reference is valid. You know the drill, the editor registers a selection, which later the TypeScript client will map back to the refactor it received in the previous request. From that, it constructs the commands arguments following the TypeScript protocol. And when it receives the result, it will return the workspace edits, which include file modifications, additions and removals that the refactor implies.

Let's go back to the handler for this refactor. When asked to apply the action, it will again ask the compiler for the node that's being inline, the references to it, as well as the expression we'll replace the variable with. It then updates all the references to use the value instead of the variable identifier. And finally, it gets rid of the now on use variable. And ta-da! After the editor reads and translates the response, the refactor is finally applied.

Now that you're TS Server experts, impress editor and TypeScript maintainers the next time you encounter a bug and create a GitHub issue. Say that when applying the code action, the modified line is off by one. Without further context, I would dare to say that this is a language server bug, since at the end of the day the editor is blindly applying the change that the server told it to do. Also, if it's a server bug you would be able to reproduce the issue in another editor, so you can also try that. As another scenario, say that when clicking on the light bulb, the displayed list has duplicate items. This is a bit harder to say, but from my experience, I would guess that this is an editor bug, since it is the one responsible for querying the code action providers, combining the results and displaying them in the UI. As a funny story, one of the first bugs that I fixed at Microsoft was duplicate completion entries in Visual Studio. It was both a fascinating, but slightly traumatizing experience. If you really want to look like a professional, you can even take a look at the TS server logs, or by setting TypeScript trace level to verbose in VS Code, to see what exactly the server is receiving and returning. That will help pinpoint where things go downhill.

5. TypeScript Protocol and LSP

Short description:

Now that we went over how the TypeScript protocol works, you might ask if it was always designed like this. TS server kind of always existed, despite not being formally specified. Later on, TS server was moved to its own node process, as an effort to improve the performance of the IDE. This allows the same server to communicate with anyone that follows the TypeScript protocol. TS server can just care about TypeScript stuff, and the editor about everything else. Thanks to this design, we can have a TypeScript client in VS Code, a Lua implementation for NeoVim, and a Python handler for Sublime. LSP uses language-neutral types, like file URIs and document positions. So why don't we just use LSP? However, such a change would require a major rewrite of not only the server but also all of the clients that have been following this communication handshake for years. Enhanced TypeScript-specific features require custom extensions to the protocol. LSP is still a powerful extensibility solution, and even complex and popular languages like Rust, use LSP for their language service interface.

Now that we went over how the TypeScript protocol works, you might ask if it was always designed like this. The answer is a bit vague, because TS server kind of always existed, despite not being formally specified. In the early days, TS server ran in processing Visual Studio. And yes, I mean IDE and not VS Code, because VS Code didn't even exist back then.

Later on, TS server was moved to its own node process, as an effort to improve the performance of the IDE. Fortunately, that transition was smooth, because with the existing JSON protocol, going to an inter-process communication had basically no impact. From the snippets we just looked at, you might feel like translating the arguments and response might be annoying, or even redundant. However, this allows the same server to communicate with anyone that follows the TypeScript protocol. The language the client is implemented in doesn't matter, neither does the UI used to interact with the user. TS server can just care about TypeScript stuff, and the editor about everything else.

Thanks to this design, we can have a TypeScript client in VS Code, a Lua implementation for NeoVim, and a Python handler for Sublime. In fact, TS server was even an inspiration for LSP, the protocol that defines a standard over how editor tools and language servers communicate. With it, a single server can be reused in multiple development tools, and editors can support languages with minimal effort. LSP uses language-neutral types, like file URIs and document positions. This is because it is much easier to standardize the text document URI or a cursor position than it is to defining a common ground between abstract syntax trees and compiler symbols across multiple programming languages.

So why don't we just use LSP? Why stick to this custom TypeScript protocol instead of the more flexible and general language service protocol? After all, by doing that transition, there would be no need to translate between TypeScript and Editor types. However, such a change would require a major rewrite of not only the server but also all of the clients that have been following this communication handshake for years. Moreover, such a change might not mean a huge win anyway, since in order to provide rich Editor interactions, we often need to override LSP methods. Remember that LSP remains language neutral. Enhanced TypeScript-specific features require custom extensions to the protocol. An example of this is the new Move to File TypeScript refactor. With it, you can move a block of code to an existing file, which requires asking the user for the destination file name. LSP doesn't have a standard for code actions that require user input, while TS Server can evolve to do so.

That being said, LSP is still a powerful extensibility solution, and even complex and popular languages like Rust, you sell SP for their language service interface. And that's all that I had for you today. I hope that you enjoyed and learned more about how you're getting all of those type goodies. And the next time that you click on a lightbulb, you'll remember this talk.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

A Guide to React Rendering Behavior
React Advanced Conference 2022React Advanced Conference 2022
25 min
A Guide to React Rendering Behavior
Top Content
React is a library for "rendering" UI from components, but many users find themselves confused about how React rendering actually works. What do terms like "rendering", "reconciliation", "Fibers", and "committing" actually mean? When do renders happen? How does Context affect rendering, and how do libraries like Redux cause updates? In this talk, we'll clear up the confusion and provide a solid foundation for understanding when, why, and how React renders. We'll look at: - What "rendering" actually is - How React queues renders and the standard rendering behavior - How keys and component types are used in rendering - Techniques for optimizing render performance - How context usage affects rendering behavior| - How external libraries tie into React rendering
Modern Web Debugging
JSNation 2023JSNation 2023
29 min
Modern Web Debugging
Top Content
Few developers enjoy debugging, and debugging can be complex for modern web apps because of the multiple frameworks, languages, and libraries used. But, developer tools have come a long way in making the process easier. In this talk, Jecelyn will dig into the modern state of debugging, improvements in DevTools, and how you can use them to reliably debug your apps.
React Concurrency, Explained
React Summit 2023React Summit 2023
23 min
React Concurrency, Explained
Top Content
React 18! Concurrent features! You might’ve already tried the new APIs like useTransition, or you might’ve just heard of them. But do you know how React 18 achieves the performance wins it brings with itself? In this talk, let’s peek under the hood of React 18’s performance features: - How React 18 lowers the time your page stays frozen (aka TBT) - What exactly happens in the main thread when you run useTransition() - What’s the catch with the improvements (there’s no free cake!), and why Vue.js and Preact straight refused to ship anything similar
The Future of Performance Tooling
JSNation 2022JSNation 2022
21 min
The Future of Performance Tooling
Top Content
Our understanding of performance & user-experience has heavily evolved over the years. Web Developer Tooling needs to similarly evolve to make sure it is user-centric, actionable and contextual where modern experiences are concerned. In this talk, Addy will walk you through Chrome and others have been thinking about this problem and what updates they've been making to performance tools to lower the friction for building great experiences on the web.
TypeScript and React: Secrets of a Happy Marriage
React Advanced Conference 2022React Advanced Conference 2022
21 min
TypeScript and React: Secrets of a Happy Marriage
Top Content
TypeScript and React are inseparable. What's the secret to their successful union? Quite a lot of surprisingly strange code. Learn why useRef always feels weird, how to wrangle generics in custom hooks, and how union types can transform your components.
React's Most Useful Types
React Day Berlin 2023React Day Berlin 2023
21 min
React's Most Useful Types
Top Content
We don't think of React as shipping its own types. But React's types are a core part of the framework - overseen by the React team, and co-ordinated with React's major releases.In this live coding talk, we'll look at all the types you've been missing out on. How do you get the props type from a component? How do you know what ref a component takes? Should you use React.FC? And what's the deal with JSX.Element?You'll walk away with a bunch of exciting ideas to take to your React applications, and hopefully a new appreciation for the wonders of React and TypeScript working together.

Workshops on related topic

React Hooks Tips Only the Pros Know
React Summit Remote Edition 2021React Summit Remote Edition 2021
177 min
React Hooks Tips Only the Pros Know
Top Content
Featured Workshop
Maurice de Beijer
Maurice de Beijer
The addition of the hooks API to React was quite a major change. Before hooks most components had to be class based. Now, with hooks, these are often much simpler functional components. Hooks can be really simple to use. Almost deceptively simple. Because there are still plenty of ways you can mess up with hooks. And it often turns out there are many ways where you can improve your components a better understanding of how each React hook can be used.You will learn all about the pros and cons of the various hooks. You will learn when to use useState() versus useReducer(). We will look at using useContext() efficiently. You will see when to use useLayoutEffect() and when useEffect() is better.
React, TypeScript, and TDD
React Advanced Conference 2021React Advanced Conference 2021
174 min
React, TypeScript, and TDD
Top Content
Featured WorkshopFree
Paul Everitt
Paul Everitt
ReactJS is wildly popular and thus wildly supported. TypeScript is increasingly popular, and thus increasingly supported.

The two together? Not as much. Given that they both change quickly, it's hard to find accurate learning materials.

React+TypeScript, with JetBrains IDEs? That three-part combination is the topic of this series. We'll show a little about a lot. Meaning, the key steps to getting productive, in the IDE, for React projects using TypeScript. Along the way we'll show test-driven development and emphasize tips-and-tricks in the IDE.
Designing Effective Tests With React Testing Library
React Summit 2023React Summit 2023
151 min
Designing Effective Tests With React Testing Library
Top Content
Featured Workshop
Josh Justice
Josh Justice
React Testing Library is a great framework for React component tests because there are a lot of questions it answers for you, so you don’t need to worry about those questions. But that doesn’t mean testing is easy. There are still a lot of questions you have to figure out for yourself: How many component tests should you write vs end-to-end tests or lower-level unit tests? How can you test a certain line of code that is tricky to test? And what in the world are you supposed to do about that persistent act() warning?
In this three-hour workshop we’ll introduce React Testing Library along with a mental model for how to think about designing your component tests. This mental model will help you see how to test each bit of logic, whether or not to mock dependencies, and will help improve the design of your components. You’ll walk away with the tools, techniques, and principles you need to implement low-cost, high-value component tests.
Table of contents- The different kinds of React application tests, and where component tests fit in- A mental model for thinking about the inputs and outputs of the components you test- Options for selecting DOM elements to verify and interact with them- The value of mocks and why they shouldn’t be avoided- The challenges with asynchrony in RTL tests and how to handle them
Prerequisites- Familiarity with building applications with React- Basic experience writing automated tests with Jest or another unit testing framework- You do not need any experience with React Testing Library- Machine setup: Node LTS, Yarn
Best Practices and Advanced TypeScript Tips for React Developers
React Advanced Conference 2022React Advanced Conference 2022
148 min
Best Practices and Advanced TypeScript Tips for React Developers
Top Content
Featured Workshop
Maurice de Beijer
Maurice de Beijer
Are you a React developer trying to get the most benefits from TypeScript? Then this is the workshop for you.In this interactive workshop, we will start at the basics and examine the pros and cons of different ways you can declare React components using TypeScript. After that we will move to more advanced concepts where we will go beyond the strict setting of TypeScript. You will learn when to use types like any, unknown and never. We will explore the use of type predicates, guards and exhaustive checking. You will learn about the built-in mapped types as well as how to create your own new type map utilities. And we will start programming in the TypeScript type system using conditional types and type inferring.
Deep TypeScript Tips & Tricks
Node Congress 2024Node Congress 2024
83 min
Deep TypeScript Tips & Tricks
Top Content
Workshop
Josh Goldberg
Josh Goldberg
TypeScript has a powerful type system with all sorts of fancy features for representing wild and wacky JavaScript states. But the syntax to do so isn't always straightforward, and the error messages aren't always precise in telling you what's wrong. Let's dive into how many of TypeScript's more powerful features really work, what kinds of real-world problems they solve, and how to wrestle the type system into submission so you can write truly excellent TypeScript code.
Practice TypeScript Techniques Building React Server Components App
TypeScript Congress 2023TypeScript Congress 2023
131 min
Practice TypeScript Techniques Building React Server Components App
Workshop
Maurice de Beijer
Maurice de Beijer
In this hands-on workshop, Maurice will personally guide you through a series of exercises designed to empower you with a deep understanding of React Server Components and the power of TypeScript. Discover how to optimize your applications, improve performance, and unlock new possibilities.
 
During the workshop, you will:
- Maximize code maintainability and scalability with advanced TypeScript practices
- Unleash the performance benefits of React Server Components, surpassing traditional approaches
- Turbocharge your TypeScript with the power of Mapped Types
- Make your TypeScript types more secure with Opaque Types
- Explore the power of Template Literal Types when using Mapped Types
 
Maurice will virtually be by your side, offering comprehensive guidance and answering your questions as you navigate each exercise. By the end of the workshop, you'll have mastered React Server Components, armed with a newfound arsenal of TypeScript knowledge to supercharge your React applications.
 
Don't miss this opportunity to elevate your React expertise to new heights. Join our workshop and unlock the potential of React Server Components with TypeScript. Your apps will thank you.