One Config File To Rule Them All

Welcome, everyone. My name is Marco Ippolito, and today I will talk about one config file to rule them all. So, who I am? I'm a Senior Security Engineer at Herodevs, and I'm a member of the NodeJS Technical Steering Committee and a releaser. So, NodeJS in the past years has shipped a lot of very cool features. For example, the test runner, watch mode, things that previously you needed to download from NPM, native TypeScript support is also another big one I worked on personally. We have test coverage and finally permission model to improve the security of running NodeJS application.

So, what does all these features have in common is that they all require some sort of configuration. For example, if you want to configure the test runner, you need to pass a lot of flags, and the same thing applies for most of the NodeJS features that we talked about. There are some flags for watch, some flags for the permission model, some flags for the coverage, some other flags for the tracing. It's a lot of flags. Honestly, I don't even know all these flags. I need to go check the documentation, but they are a lot. So, obviously the problem with that is that a lot of flags becomes very hard to know all of them.

Let's start with a simple use case, and I will show you how we can improve the developer experience. So, let's take a flag called experimental transform types. If you have been following NodeJS TypeScript integration, you know that NodeJS does not support all the TypeScript syntax. To enable this 100% support, you need to pass this experimental transform types flag. So, in this case, we can run enums. We have the color red, and we create a file.ts, and we run it. So, we pass Node – experimental transform types, and it works. It prints red and prints an experimental warning. So, how do we remove the experimental warning? We can pass another flag. This flag is disable experimental warning. And, boom, we have red without the warning. So, let's add some tests. In order to imagine how our application is growing, we want to run some tests. We need to pass the – test flag, and then it will run a test suite. Right? Because we all know that test is one of the first things we need to add when we create our application. Maybe we add some coverage. Okay? So, we need to pass experimental test coverage, and then we configure the test coverage with the number of lines we want to have them at 100%.

And, boom, we have this table here with the test coverage. What else we can do? We can do watch mode. So, if in the past, you were using Nodemon for hot reloading, now you can use –watch. And if we change something, the application will start. So, this is you right now, because you have so many flags that it's very hard to read.

Let me go back for one second. Like, we have one, two, three, four, five, six flags. Now, imagine all these flags inside your package JSON. It would be very wide. So, you need to scroll horizontally to see all of them. And this is not great. We can do better, all right?

So, if we run – if we check the node manual, so we run man node, we will see a big list of things that we don't care about. But if we look at the last one, we can see there is an environment variable that the Node.js application will read. And it's called node options. So, node options is another way to pass to the Node.js application all those configuration flags. Not all the flags are supported. There is documented which ones are not supported, but most of them are.

So, node options is also very useful when you are running another application, but you don't have control over the node command. For example, when you are running something with NPX. A use case I find very useful is to pass node option –abort on uncaught exception with NPX. So, in this way, if there is a bug, I can see it without being swallowed by NPX. So, what do we do now? We create this environment variable called node options, and we pass some of the flags that are allowed inside the node options. And so, we can remove all the flags after the node command, and we can see we are just running three flags and it works in the same way.

So, we can also use –mfile to set the node options from a file. So, we create a .mfile, we put inside this file the node options, and then we pass it. So, if in the past you were using .env, now you don't need to install it anymore because it's built in the Node.js application. So, we create a file, we put the node options inside, and then we run node –mfile and the same flags as before. Watch, experimental, test, coverage, and test. We cannot put those flags inside the node options because those are not allowed. All right.

So, this is an improvement, but it's still not great. I think we can do much, much better than this. Like, still you have .mfile without autocompletion for IDE. You have to know which flags are allowed, which are not allowed. It's suboptimal developer experience. We can do better. So, what Node.js is missing is actually a file-based initialization configuration. So, the name sounds scary, but if you are used to other languages, PHP has one, Java has one, .NET has one, Ruby has one. All major programming languages' runtimes have one. And also, other JavaScript runtimes have one. There is the dna.json and the banfig.toml. So, Node.js needs something similar to this to configure the application with just a file. All right. So, this has been discussed for years. This discussion is from July 2024. And there was a lot of back and forth with the Node.js maintainers to, like, how do we do this and what is the best way we can do this? A lot of back and forth. And this was February 2025.

I sent a PR. So, at the time I was not sure what was the, like, how the feature would grow and the various evolution of this feature. So, at the time it was called Node.json. And basically you could pass an experimental config file and Node would parse this JSON file and do what we will see in a few seconds. So, in Node 23, this feature landed. This is called experimental config file. And it consists of two flags, two major flags.

The first flag is called experimental default config file. So, if you pass the experimental default config file, Node will search for a Node config JSON. So, the file needs to be called Node config JSON. The reason why we couldn't use Node.json is because it's already used by some NPM packages in the wild and we don't want to break them. So, if you just pass this flag, you can Node will automatically search for it. Otherwise, you can specify a JSON file of your choice by passing the flag experimental config file. So, you can use whatever file you want. You can put it in another folder. The only important part is that it is a JSON file.

So, the file looks like this. So, it has a schema, which is very important. So, the schema needs to match with exactly the Node version that you are running. So, if you are running Node 24.7, the schema needs to match that version. Otherwise, the config and the runtime will not be like there will be a difference between the flags that are supported and it might break. So, you want them to match always. Also, the schema gives you auto-completion. It gives you IDE support. It's very good. We will see a little bit later. So, in this case, you have a field called Node options, which is the same thing as the Node options that we were using before. And we can put inside the flags that we were using. But now we have no longer an environment variable, but a configuration file. So, the Node options field contains the same values as in Node options.

So, the same that are allowed, they work in the same way. And not all V8 flags are allowed. So, what are V8 flags? You know V8 is the JavaScript engine inside Node.js that runs JavaScript code. One example of a V8 flag is stack trace limit. So, you can increase how big the stack trace looks like. So, for example, you can make a stack trace this big. This is very useful if you want to debug like a very nested object or you simply want to have the Java field in JavaScript. If you're used to Java, it works both ways.

Also, this is a fun fact. So, there are a few flags in Node.js that do nothing. They are called no-op. So, they are there for compatibility reasons. We decided not to support those flags because they don't do absolutely anything. So, when a flag is present in both the CLI, the Node options, and the config file, there is a priority list. This is important. So, the CLI, if you run Node something, that takes priority. Then, we have the Node options as an environment variable. Then, we have the configuration file. And, at the end, we have the Node options from the .env, from the .env file, the one we saw before.

Another very big improvement in DX is test runner global configuration. So, as we talked about previously, not all the flags are supported inside the Node options. For example, not all the test flags are supported. So, this issue has been there since 2022. So, it's been a very long time this was needed. And so, we decided to support a new namespace inside the configuration file just for the test runner. So, this landed in Node 24. We have a new namespace called test runner that enables the complete configuration of the Node.js test runner. It looks like this. So, you have a field called test runner.

So, you have a field called test runner. And, inside this field, you can pass whatever configuration you want. It's all supported, even configurations that are not usually supported in Node options. And, this looks like this. So, you still need to enable it by passing dash dash test, but we have removed a lot of the other flags.

Another feature that was needed is the watch name namespace. It's the same way of the test namespace. We added a new namespace for the watch. As you can see, it works in the same way. You pass watch, and it's watch preserve output true. Same thing. Permission model. Same thing. You can pass the namespace permission, and you can pass inside all the fields that you want to use. This is available in Node 25.

So, in the past months, we had a few changes. So, we renamed the test runner field to test. And now, whenever you have a namespace, for example, you pass the namespace test or the namespace watch or the namespace permission, the flag is no longer needed because it will be enabled by default. So, if we have test here, the flag dash dash test is no longer needed. Same for watch and same for permission. So, this is what a modern configuration file looks like. And we can see in our CLI, let's use this as an example of a test where we use the permission model. So, this test will just try to fetch something from the Internet and check if the access to the network is denied. If we try to run it, we can just run Node dash dash experimental default config file and test. And everything else is enabled by the configuration file. So, we have skipped all the flags possible. We just need one, which is experimental default config file. So, we have improved the developer experience by a lot because the user now needs to just configure one file and can run the Node.js application.

So, a few questions that I am asked a lot. So, does it make my application startup slower? The answer is no, it's negligible. Why a JSON configuration file and not a YAML in the terminal? The reason is that Node.js has a JSON parser built in and doesn't have any other parser like YAML in your terminal. So, for convenience. Should I publish it? The answer is no. The consumer would be like the Node config JSON in Node modules will be ignored. Is it production ready? No, it's still experimental. And can I put custom configuration in the Node config JSON? The answer is yes, but it will be ignored.

So, what's next for the development of this feature? More namespaces, help text in the JSON schema. This actually landed a few weeks ago. So, as you can see, the IDE will explain to you what the flag does. In this case, experimental test coverage tells you that enables the coverage in test runner. This was discussed to enable package JSON by default, like to put the configuration in packages instead of a Node configuration file. But the reason why is there is a lot of chaos in the Node.js configuration ecosystem. We had, yeah, so it was very scary to add a new configuration file.

And a lot of people pushed back on this because like we don't want another configuration file. So, we had a poll to change the default value and put it in the package JSON. But we did not reach consensus. And there are other issues such as the schema validation of the package JSON. So, we discarded that idea. And the only thing that's left is to market as a release candidate and unplug it. So, thanks for listening. In the QR code, you can find all the information. And see you next time. Bye.