cloudflare
Configuration page doesn't accurately reflect TOML structure
Which Cloudflare product does this pertain to?
Workers
Existing documentation URL(s)
https://developers.cloudflare.com/workers/wrangler/configuration/
Section that requires update
wrangler.toml
What needs to change?
The example TOML is helpful, but misleading. For example, the documentation has kv_namespaces in the [vars] table, but kv_namespaces is intended to be a top level value. Other examples are the misplaced, top-level keys compatibility_flags, compatibility_date, and services
How should it change?
Any top-level keys should be listed above all table names to clarify the TOML's structure.
Additional information
Because TOML doesn't support a schema format, the only way to understand the config options is accurate documentation or reading the parsing implementation. An alternative fix could be switching to a config file format that supports a schema like JSON or YAML, but that is probably orthogonal to fixing this particular issue.
The issue with using tables like [vars] is that anything after that, up until another table or end of file, is under [vars].
There is a lot of pitfalls with TOML which can trip you up pretty easily.
[vars]
KEY = "value"
kv_namespaces = [
{ binding = "TEST_NAMESPACE", id = "", preview_id = "" }
]
Looks like it should be fine, right?
vars:
KEY: value
kv_namespaces:
- binding: TEST_NAMESPACE
id: ''
preview_id:
YAML makes it immediately obvious where the issue is - but one of the issues with YAML is that you can't use tabs (only spaces) and there's accessibility issues there.
There was a PR to add YAML to wrangler2 but it was closed: https://github.com/cloudflare/wrangler2/pull/1302
I discussed the array of tables approach in https://github.com/cloudflare/cloudflare-docs/issues/4695 which is a lot more foolproof imo - but we decided on inline tables.
It looks like we'll be moving to array of tables though, i.e for KV in https://github.com/cloudflare/cloudflare-docs/pull/5051. They don't run into the same issues as being 'inherited' by a table.
[vars]
foo = 'bar'
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = '<YOUR_BUCKET_NAME>'
preview_bucket_name = "<YOUR_TEST_BUCKET_NAME>"
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = '<YOUR_BUCKET_NAME>'
preview_bucket_name = "<YOUR_TEST_BUCKET_NAME>"
vars:
foo: bar
r2_buckets:
- binding: MY_BUCKET
bucket_name: <YOUR_BUCKET_NAME>
preview_bucket_name: <YOUR_TEST_BUCKET_NAME>
- binding: MY_BUCKET
bucket_name: <YOUR_BUCKET_NAME>
preview_bucket_name: <YOUR_TEST_BUCKET_NAME>
I think we should use them personally. However, I don't know if they play with environments (https://developers.cloudflare.com/workers/platform/environments/) and maybe you'd need to use the current kv_namespaces inline table when using something like [env.dev]
In my opinion, I'd also prefer the format of https://developers.cloudflare.com/workers/wrangler/cli-wrangler/configuration/
Rather than a giant codeblock, having it split up into headings like it used to be.
It looks like we'll be moving to array of tables though, i.e for KV in #5051. They don't run into the same issues as being 'inherited' by a table.
Agree, an array of tables does help, but gets messy nested inside of [env]
In my opinion, I'd also prefer the format of https://developers.cloudflare.com/workers/wrangler/cli-wrangler/configuration/
yes, this was a much better format -- probably much easier to maintain as well.
but gets messy nested inside of [env]
The joys of TOML and their table syntax.
Yeah, this would look like kv_namespaces is apart of [env.dev] but it isn't:
# invalid
[env.dev]
[[kv_namespaces]]
binding = '1'
id = '2'
Similarly, you can't define [vars] under [env.dev] since [vars] is a brand new table:
# invalid
[env.dev]
[vars]
binding = '1'
It would instead need to be like this:
# valid
[env.dev]
vars = { binding = '1' }
I think you need a degree in TOML to be able to comprehend it at this point.
If you go with inline tables or array of tables, you're going to need to include the other one inevitably since there's quirks that require both - and probably explaining that in the documentation too.
If you stumble across this example from the old configuration docs, you'll notice that [vars] is defined twice which isn't valid TOML too.
Enough TOML pain prompted me to create this concept: https://kian-wrangler-configuration.cloudflare-docs-github.pages.dev/workers/wrangler/configuration/