Transcript from the "API Extractor Setup" Lesson
[00:00:00]
>> What we're going to do next is a two step process for having an excellent documentation for this monorepo. Now, as you start building software that's more and more complicated apps that are more complicated It starts to. It starts to become important to have documentation even for the app itself.
[00:00:26] Right? You have a team of like 15 or 20 people having Good API Doc's is an important way that you can share share information in a situation where nobody is an expert in everything. And you don't want to have to go. You know, ask somebody and have them explain it to you like it's a very expensive way to pass information.
[00:00:46] And it's lossy because they might not be available or they might. Give you a short and quick and then complete explanation. So, API Doc's are not just for libraries. And I'm going to show you a way that you can set this up. such that if you just document your code Well, in a way that will pull just you're already going to be motivated by having good tooltips right and having good autocompletes.
[00:01:11] If you document your code well, such that you have a good developer experience, you're going to get some great extra stuff for free. In particular, we're going to have an API report. So we can understand how a given proposed code changes. Has an effect on the public API surface of any one of these little modules, right?
[00:01:38] If you treated them as libraries, you want types and data, and utils. At the very least, these three, you want those to be relatively stable. Especially like in a situation where If you do what I'm suggesting you can do, and kind of mix and match these potentially you have a mobile app or you have a desktop app in addition to the web experience.
[00:02:02] As soon as you have multiple consumers having a stable way to talk to them is of critical importance. So we're gonna build that API report so that you can understand for a given change, how will this affect my API? The second thing we're gonna do is use that same information to provide some turn key documentation that works beautifully with GitHub.
[00:02:25] So here we go. The first thing we're gonna do is install a couple of new packages. And those are called API extractor and API documenter. Actually, let's just do API extractor first. Now this is a so workspace wide tool. And so we're just going to install it as a workspace dependency.
[00:02:48] Microsoft API extractor, So the next thing we're gonna do is we're gonna say yarn api-extractor init. And that will create a baseline config file for us. And we're gonna rename that config file soon as it's generated. So it's API extractor js. This is going to be again, a common file that other packages extend from.
[00:03:32] And I'm gonna leave it at the root of the project here, cuz actually, I don't think we need to in this case Let's move it into the packages folder. That's where I like to keep the sort of base. And we're going to API extractor base. This is not to be used directly baseline configuration.
[00:03:59] I'm going to save that. And then I'm going to go into our course files. And in Section 11 API report, there is another API extractor base. So I'm going to go get add. And then I'm going to copy the contents of this file into the new one we just created.
[00:04:18] Why am I doing this? I want to show you what I've changed. And now we can see in the gutter here, all of the things that have sort of flipped. So, starting from the top, I have, let's see was this enabled by default Looks like I have enabled it.
[00:04:43] So this creates a JSON file that can be used later. To generate API documentation. We know we're going to do this so we may as well enable it now. And we're placing this file in a particular path. There's going to be this temp folder. You don't have this yet, because it's get ignored.
[00:05:02] And I still have mine here, but I can point to it thankfully, because it's still here. So this project folder is going to be one of the packages in your mono repo. So we're going to go one directory up, packages, one directory up to the root. And then into the temp folder.
[00:05:20] And then finally, we're creating a JSON file that has the package name in the filename. So what we should end up with is this, four files, each representing docs for one package within your monorepo. We're going to enable this feature called a dtsRollup. So what this allows you to do is define on a per export basis, what is public?
[00:05:51] What is internal only you may expose things through your modules that are strictly available for testing purposes. You just need to unit test a function. You have to expose that function. But you can mark it. As you know, this is just for internal use. API extractor supports the concept of betas.
[00:06:13] So you can have several of these DTS roll ups, each of which includes complete type information for your project. And one's for the stable release, one's for the beta, and then one is an untrimmed roll up that contains all of your internal types as well. And depending on what your purposes, there's there may be a good reason to use each of them.
[00:06:35] For example, In some cases, packages within your mono repo may communicate with each other through non public API's. Right So, they may change and you may not call that a breaking change because these things are only supposed to talk to each other Through that path. So we're going to enable these DTS roll ups.
[00:07:00] It's a great way to be more deliberate and explicit about the type of information you expose to your users. And for that matter, it also allows you to have a concept that other languages call package, private. So, Java allows this, where you can say, I'm creating a package called com.fernenmasters.shclack and anything within this package can access these fields on the class but nothing outside of the package.
[00:07:31] We don't have that concept in the Java script world. Right? You're either in the module or you're not. And so this Enables that concept and there's a good rationale for why that exists and it's a useful one. And in addition to this, I'm also just stating where various DTS roll ups should be placed.
[00:07:56] They're going to be placed in each packages dist folder. Alongside the original output, and we're just going to modify the package JSON of each package so that it's pointing to these roll ups instead of pointing to the raw type information that comes straight out of the compiler. So we've got one for our untrimmed file path and I'm calling this private.
[00:08:18] We've got a beta. And then we've got one with no qualifier at the end, right. And this is the public stable API. This is what if you change this in a backwards incompatible way, this is where you should be major versioning That is all I've changed the other things you can do here.
[00:08:40] So this behaves kind of like a linter, as we'll see. And this allows you to do things like configure whether things are treated as warnings or errors, whether they're surfaced in the console, or they're added to this API report file where you'll just see notes like this was a problem.
[00:08:57] I found here. You have a lot of different knobs you can turn here. And these each represent a rule of sorts. So let's keep keep on going here. I need to create I'm going to go back up into our starter files here. So I have a folder here that's like packages slash pkg.
[00:09:27] And then this API extractor JSON thing. Just copy this into the root of every one of your packages didn't want to give you four because it's the exact same file. You're just going to put it in each. 123 and 4. Again, this follows this time, Convention, have one meaningful confide file, and then these really thin ones that I'll extend from it.
[00:10:00] So if we want to change options, we're changing things on the whole project. By default, at least, of course, you could go in here and you could make little adjustments. But I don't want to have to do that by default. I want as much consolidation as I can have because I If you're bothering to make a mono repo, you're gonna end up with a lot of packages in here.
[00:10:21] And you just want to think about the per package maintenance overhead. You don't want that number to be high because there's a big coefficient next to it. Right? So if it's like takes an hour of my time a week, and there are 50 packages, well, that just became your full time job and then a little bit You know, you can't you can't have that.
[00:10:41] So you want that number to be really small per package maintenance.