ESLint One for All Made Easy

Hello everyone, thanks a lot for having me and hope you're enjoying the conference so far. It's a bit shame that I couldn't come to Berlin in person this time, but I hope you will find my topic today interesting.

So first, let me introduce myself a bit. My name is Anthony Fu and I'm the coaching member of Vit, Vue, and Nuxt. I also create a few open source projects like Vitest, Lightdiv, Unocetus, et cetera. I'm also maintaining a few projects like ESLink, StyleAsync, Shiki, 2slash, and so on. I'm currently working at Nuxt Lab on the framework team.

So, as you can see, I'm pretty enthusiastic about open source, which driven me to work on a lot of projects. I love building tools and figuring out solutions of problems I encountered. For example, the slide you are looking at is powered by Slidev, a markdown-based presentation tool that's built on top of web technologies. It was born when I found the existing tools were not flexible enough for me to present my code. Similarly, when I look into ESLink and its ecosystem a few months ago, I find many things are quite interesting with a lot of potential, but was not yet fully explored. So today I would like to share with you some of my findings and practice during my recent explorations around it.

So, 11 years since ESLink came out, at this moment, it's easily one of the most popular tools in the JavaScript ecosystem that almost every project uses. Despite it has been around for such a long time, it's a tool that's still consistently improving and evolving.

Today, I'd like to give you a bored and ambitious topic, ESLinked, one for all, made easy. To share with you some of the new perspectives and patterns of using ESLinked with the latest features that they just rolled out.

So you're probably already aware that ESLinked v9.0 was released around 7 months ago. The main highlight of this major version is the rolling out of the new configuration system for ESLinked, called the FlatConfig. In case you never heard about it or haven't dig into the docs yet, here let me do a quick comparison between the legacy ESLinked-RC config and the new FlatConfig for you.

To differentiate between those two config formats is rather straightforward. The legacy config is named .eslinked-rc, that supports various extensions, which might also read it from your package.json. The FlatConfig, on the other hand, would only load from eslinked.config.js, a JavaScript config file as a single source of truth.

And when it comes to reusing the shared config, the legacy config formats implicitly use a conventional-based extends properties to load the config from your local node modules. You would need to learn the convention a little bit to know how it resolves. While the FlatConfig will use native imports, where it's more explicit and gives you a lot more control.

And for plugins, in the legacy config, it takes an array of strings, which is again a convention-based and coupled with a plugin's package name. Now in the FlatConfig, it takes a named object for plugins. This means you can now rename plugins easily or switch to a fork without being forced to change every rule in your config.

Also, due to the inherent nature of extends, might result a very complex tree structure in the shared config, because the shared config can also have nested extends inside. In the FlatConfig, it gets a lot simpler. When you explicitly import the shared config as a multiple objects or arrays, and you can compose them into a single flat one, and that's also why it's called FlatConfig.

And for a little bit more context, here is a graph I drew to demonstrate the timeline. While the FlatConfig might sound new to some of you, it has actually been planned for 5 years already. The RFC was created in January 2019. The first imputation is available in version 8.21, ax experimental, which was two years ago. It becomes stable in version 8.45, and then it becomes the default in the recent version 9. In between, the ESLink team has published multiple blog posts to explain the reason why they want to introduce a new format, and share the roadmap of rolling out. That's a lot of effort spent across in this five years plan. So huge respect to the ESLink team.

So as we mentioned in the previous slides, the biggest benefit of FlatConfig is now is in JavaScript, where you have the full control. It uses native import to resolve the plugins and the configs, making the inheritance and the overriding a lot simpler. Because it's full in JavaScript, shared config can be a factory function that takes users' options, and the user can have a lot more capability to do customizations to their specific needs.

Before we talk about the new exciting stuff, let me quickly go through the tools for migrating your legacy config to the new FlatConfig in case you might need them. You have a CLI as eslink-migrate-config that automatically converts your legacy config file to the FlatConfig. Some runtime utilities for the compatibilities will also be introduced automatically along the way as well. I would recommend you to check the ESLink docs and the migration guide for more detailed instructions.

And now, let's talk about the cool new stuff and possibilities that's enabled by this new FlatConfig format. The first one is the eslink-config-inspector, a visualized step tool that allows you to inspect and play with your final resolved config. You can try it by running eslink-inspect-config in your CLI under the project root. It will open a browser page with UI like the one you see on the right.

So the first thing it does is to render each config item you have. You can see all the config lists are here, and because it's flat. Here I have a rather complex config setup with many configuration items, but with the name provided by each configuration, you can easily see and understand the purpose of each of them. You can also expand each item to see how it contributes to the final config, like how many rules it enables and what's the target file, etc. And in each rule, you can also see their options, a short description, and also a link to their documentation page.

In the config inspector, you can also enter the file paths to test how the rules are enabled for that file. For example, here I can type folo.json to see these rules apply to this file, and I can also change to pack.json, and I can see that there is also a specific rule that only applies to pack.json, and here is all the merged rules for this file path. And in the other tab, you can also browser for every rule that's available in your project, given the project you have installed, and you can filter them out and see which rules you are using and which rules you don't, and what are the recommended ones, and which are deprecated.

Here I have my config preset as an example. The codeframe here reflects to my ESlinks config on my disk. The config is a factory function that takes some rather high-level options. With the config inspector, we can see how it resolves based on the options we provide. We can also try to change some options to see how it affects the result. For example, if I want to have TypeScript enabled for this project, I can just change the TypeScript from false to true. When I save it, you can see there are three new TypeScript-related items appear on this config. I can optionally change this to an option and provide the path to my tsconfig.json, When I save it, it'll enable the TypeScript-aware rules for certain types. You can see this has a lot of potential. You can change a lot of things. From one more example, you can disable view, you can enable react.true. When you save it, you can see the react and react-typeScript-aware things. Those are automatically without you to worry about the details.

Those are automatically without you to worry about the details. To make the config customization easier, I also made a small library called eslink-flag-config-utilities. For example, here is the flag config you might have. Depends on how each shared config is constructed, some might be a planned object, some might be an array, and some might be a constructor that returns an object, array, or even a promise. When you use them together, it's usually your responsibility to join them together with their proper handling into a single array.

With the config utilities, I made the utilities called Compose, which will automatically resolve different types of the config and resolve the promise and merge them together. It also provides some trim action where you can do insert extra config anywhere you want or overriding some config without the need to handle the merge manually. And then thanks to the flexibility and also the full context available in the flag config, it also makes the type generation possible. Simply wrap the entire config array you expect with the type gen function, it can generate a local TypeScript declaration file based on the plugins you have installed. This provides you with the autocomplete and the type check for all the rules you are using. And so here, I'd like to bring back the title, One for All. With the maximized flexibility and customizability we have, it's not possible to have a single shared config that covers all different types of the project.

So here, I can do a quick comparison to show what I mean. In the flag config, a shared config can be a factory function that takes user options, which we couldn't do that in the Lexi config. Imagine if I want my config to work on both TypeScript and non-TypeScript project, Vue and non-Vue project. I would usually need to set up a monorepo and publish multiple configs for different combinations. As you can see, it doesn't scale well, and we are doubling the amount of the combination for each option. The flag config allows you to provide more semantic options and toggles each feature dynamically, making one single config able to adapt to different projects. And because of that, we could have a high-level abstraction to absorb the underlying complexity and provide a minimum configuration interface like Prettier, where the end users don't need to worry about the underlying details but still have all the controls to do so when they want to do.

Flag config also made it possible for MetaFramework to provide project-aware configs. For example, in Nuxt, we have a file-based routing, auto-import components, server API directories, etc. Files under different folders or different names may have different purposes with different constraints. In Nuxt, we had a Nuxt ESLink module that's generating a sub-ESLink config based on the user's project setup, where users can extend from and keep adding their own custom rules. This is one direction of possibility with flag config we are currently exploring, but we believe there will be many more interesting approaches coming to the community for different MetaFramework or general-purpose things.

To me, I see ESLink as a mutual powerful AST toolkit that has a large ecosystem on its back. For example, I want to say that ESLink can also be a formatter. It is certainly not new, as many projects have been using ESLink that way since the very beginning. But this topic is actually a little controversial, which you might hear people saying that you should use a dedicated formatter like Pretier or Dprint instead. But to me, I see this all thumbs to those stylistic rules takes a lot of maintenance effort from the ESLink team.

But to me, I see this all thumbs to those stylistic rules takes a lot of maintenance effort from the ESLink team. Last year, ESLink and Tysquare ESLink teams decided to deprecate those stylistic rules from the core. And then I initiated the ESLink stylistic project, gathering all these stylistic rules for JavaScript, Tysquare, and JSX into these organizations and make a community to maintain them. I keep using ESLink as a formatter as I see it has much more flexibility and customizability than Pretier due to ESLink's pluggable nature. If you are using VS Code, you can set editor.codeaction on save to auto-fix ESLink errors on save. And you can also use eslink.rules.customization to silence those stylistic rules in your IDE. So they work more like a formatter. For the other code editors, I believe there are similar options to do the same.