A case for netlify.json

Features
, , ,
1

I’d like to make a case for supporting netlify.json as alternative to netlify.toml, in addition to the thoughts shared in Netlify.toml vs netlify.yaml - #7 by atishay and Allow Netlify config in JSON or YAML instead of only TOML - #3 by FunctionDJ.

  1. JSON is universal. Anyone doing web development already needs to know it. Compared to JSON, TOML is fairly obscure. I’m not sure I’ve used it aside from netlify.toml.
  2. JSON is intuitive and unambiguous. I admit there’s some subjectivity here, but considering my first point, far fewer people are going to be confused by JSON than TOML, especially when it comes to arrays and deep nesting.
  3. The biggest argument for using YAML, TOML, or anything else over JSON – lack of comments – is easily overcome by using a JSONC parser on the netlify side. You could also support the .jsonc extension in addition to .json, and that would give an easy way to support syntax highlighting for comments without additional editor configuration.
  4. You can provide a great out-of-the-box editing experience for json by defining a schema for it. As a rough demonstration, I converted the example netlify.toml file from the documentation to json, then dumped it into a schema generator, and added a couple of descriptions from the documentation. Here’s what it looks like to edit a json file using that schema in VS Code:
    Screen Recording 2024-12-05 at 1.53.02 AM

The ability to provide inline documentation and validation of the file would be huge - it would save a ton of developers a ton of time, and probably a lot of support time for you guys as well.

For me, working with netlify.toml is one of the biggest pain points of using netlify, and I think being able to use a JSON file with a well-defined schema would completely turn that experience around.

2

TOMLs also support schema. VSCode doesn’t support TOML natively, but IDEs like IntelliJ IDEA do and also support schemas, here’s an example:

image
image1045×203 15.1 KB

YAML and TOML are common formats for writing CI scripts, for example GitHub Actions use YAML if I’m not wrong. Circle CI, Render, and probably a lot more services use YAML. TOML is like a more forgiving sibliing of YAML as YAML requires very strict indenting. TOML is forgiving in that area.

I’m not opposing the idea of JSON, I can see how that’s more convenient for JavaScript devs, but all I’m saying, it’s more common to use YAML (and in turn, TOML) over JSON in such config fiiles. Adding JSON support would be a huge lift on our end for not much gain. Even if I file a request for this, it would sit in the backlog for ages as there’s not much request around this.

3

I can see how that’s more convenient for JavaScript devs

I don’t have data on Netlify’s users, but considering that Netlify is a platform for websites and webapps, I would have to think that a large majority of your users are Javascript devs who are likely using VS Code. I would certainly think it’s a large enough chunk of your user base to consider.