Support Forums

Netlify.toml vs netlify.yaml


I am a little confused by the new configuration file netlify.yaml.
I imagined it would be a drop-in replacement for netlify.toml, but without the toml file I get the following error:

No netlify.toml found. This is needed to configure the function settings. For more info: https://github.com/netlify/netlify-lambda#installation

When both of them are present I have

 failed during stage 'Reading and parsing configuration files': Multiple potential Netlify configuration files in "/opt/build/repo": netlify.toml, netlify.yaml

I would like to access the “plugins” functionality and I am not certain if it exists on the toml version of the configuration as this doesn’t seem to trigger anything:

  type = "./.netlify/plugins/xxx"

What would you recommend as the best course of action?

We haven’t quite finished implementing the json and yml support, but these are the docs: https://docs.netlify.com/configure-builds/file-based-configuration/#json-and-yaml-configuration-files .

It is definitely not implemented in the private beta for build plugins yet, so you’ll need to stick with toml as the docs advise.

No longer see YAML mentioning in docs.
Is it tied to Build Plugins release?

No, we have decided to stick with toml only.

1 Like

That’s a real shame! Is there any intention to open it up in the future?

None that I’m aware of.

Mind explaining your preference in a bit more detail so I can open a feature request for us around how you’d use it specifically / what the current system blocks you on? “I hate toml” is less useful than something like: “yaml enables inheritance and better indentation/quoting for automation needs and works with other tools” :slight_smile:

The preference to choose YAML is due to the fact that YAML is many more times popular than TOML See https://trends.google.com/trends/explore?geo=US&q=yaml,toml

This makes a smaller learning curve for new developers in the team who come from various other tools into Netlify. From AWS to Ansible its YAML all the way in the DevOps space and, the TOML syntax is one more hurdle for new comers to cross to get into Netlify.

While TOML may be better in most cases, as a consumer who cares about faster on-boarding and a smaller learning curve, YAML is much better. And if the parser is good (can properly coerce values to the type it wants to understand), the proper indentation and removal of quotes makes the config easier to read.

Thanks, appreciate you taking the time to clarify! I think we’re probably going to stick with toml for the time being, but our product team will take this into account as they develop new features.

1 Like

You hit the nail on the head with indentation. I don’t hate TOML when it’s a simple definition. But I’ve had too many times when TOML’s lack of semantic indentation helps hide nested data all over the place. Meaning it becomes much harder to parse mentally and leads to weird gotchas. Sure you can hand format it to indent, but I’d rather spend my time on making things.