Advice for working with the TS Compiler API

[nonara]

Welcome! 🎉

If you've found yourself at this point, you may have already discovered that you've ventured into an area of computer science and programming that is quite advanced. If not, consider this your notice! ☺

One of the consequences of this is that the usual channels of finding answers and example code — ie. StackOverflow, documentation, forums, discord, etc. — will, more often than not, yield little to no results.

With that said, there is still hope. You can find what you need within the compiler codebase! As with many things, there is some good and some bad news with that.

The bad news is the TypeScript compiler is dense and mostly undocumented. This can seem intimidating at first, but the situation is actually less grim than it appears...

The good news is that the compiler is extremely well built and well maintained. Its structure follows consistent patterns and 'self-documenting' practices, and it is also very well organized. Although there is a lot to it, you will quickly find yourself able to pick up on the patterns used. On a personal note, I can also attest that the comparatively short time I've spent in its codebase has improved my skill more than all of my previous decades of experience taken together.

So the following is my advice after several years of working within the TS compiler codebase:

1. Do not expect to find answers for most of your questions online.

Instead – start by cloning the TS source and learning its foundational API methods. This is going to be your go-to method for learning.

A good starting point is to look at those that are related to Program, TypeChecker, and transform()

2. Learn to search the codebase

When I'm working heavily with the compiler in a project, I add the TS compiler's src directory as an external library in my IDE (WebStorm). This provides a quick way to search through the compiler's code while still remaining in my own project.

Whatever your IDE, I recommend using Find in Files on the compiler's src dir to look for methods, types, etc related to what you're trying to find. Most of what I've learned, I discovered via this method.

I'd also advise using regex patterns. When you become familiar with the naming conventions used, it is easy to find most of what you're looking for.

As an example, I wanted to find API methods to get JSDoc tags for nodes or types. Using regex, I looked for function \w+?JSDoc and found what I needed for both.

3. Use typescript-expose-internals

If you're going to work deeply with the compiler API, you'll most likely find yourself needing to use methods / types that aren't exposed. typescript-expose-internals makes using those internals simple.

4. When & how to ask for help

In a certain sense, we're in this together. With so little information out there, many of us are glad to answer a short question or two to help point someone walking the same path in the right direction.

I'd like to make the discussions panel here a place where people can ask questions regarding the compiler API so that if any of us knows the answer, we can help.

With that said, I also want to be sure that people are being respectful of others' time. If a question takes more than a minute or two to answer, it's a good sign that the person is not asking for a tip on where to look in the compiler but is rather asking for a full solution for their problem.

I don't want to discourage questions at all, but I do feel it is important to ask that you ensure that you keep your questions reasonable and not ask for full solutions to problems. If you're used to finding a full solution to copy and paste from StackOverflow without understanding it, you may want to build some more foundational experience with programming before trying to tackle problems this arena.

If, however, you've followed the advice above and you have at least some experience with the TS codebase, please feel free to ask a question, and we'll help if we can!