Feedback when app-config.yaml is filtered at runtime

Feature Suggestion

Working on the frontend, I added a key to app-config.yaml that was being filtered out when using a ConfigReader to read it in my browser for apparently no reason. Having missing keys without any feedback, I asked for help and was told I needed to:

1. Add a type definition for this key to packages/app/config.d.ts.
2. Add @visibility frontend in a comment directly above it.

While this is covered in the docs, I feel the developer experience could be improved by console.warning or console.infoing in a browser’s console when keys are being filtered out from a read app-config.yaml with a link to relevant documentation and suggestions to adjust visibility then and there.

Possible Implementation

At the time of filtering out keys, add a console.warn statement similar to

Key [key] is not marked as visible to the frontend, so it will be omitted from ConfigReader's output. 
Please add `@visibility frontend` to your app's config.d.ts to adjust it.

More info: https://backstage.io/docs/conf/defining#visibility

[OrkoHunter]

At the time of filtering out keys

Since a looot of config keys will not be available on frontend, it might be too many console warnings for an average user of Backstage.

I was thinking that a console error or warning should be printed only when you run config.get* API in the frontend and if the key is missing visibility frontend.

---

Quoting @freben

Could perhaps store all of the “potential” keys to read, even ones that were pruned - enough info for the frontend to learn that as you attempt to read a key, it failed because it has been pruned. Discern between “missing because it was never there” vs “missing because it’s been cut out”

[Rugvip]

I think adding a warning/error when filtered config values are accessed in the frontend is a great idea, I might have a look at if I can get that in. Probably just do it for development mode though, as I wouldn’t want to bloat production builds with all of that extra information. Pretty much all of the confusion that we’ve seen is during development anyway, as in “why doesn’t this config value that I just added show up in the frontend?”

@joaomilho

Adding to @TejasQ , as a short term improvement, I feel we could go further and break the build, as console warns are not obviously noticeable. It is a better DX to get the error before the confusion ensues.

The build doesn’t know what config values are being accessed, just like we can’t break the build if a certain global variable isn’t accessed at runtime. It’s actually one of the reasons the config schema exists, as it lets us break the build early when values are missing in config.

1. I wonder if conflating backend and frontend config together is the source of the problem here. The design limitations here revolve around avoiding backend secrets to leak to the frontend and if these are more clearly separated we could avoid the issue altogether and relying on comments, warning or throwing, exposing __prunedKeys, etc…

Yeah the mixing of frontend and backend config undeniably comes with its set of problems, just like mixing frontend and backend packages in the same repo. I do still think it’s worth it though, as the problem space has quite a big overlap with the problem of managing config from a bunch of different plugins. I see config schema as helping both problems, with the only extra addition needed to handle the mix being the config visibility, which we also use to filter secrets. I’m also quite happy with the security aspect of the existing solution, as it takes a conscious decision to make something available in the frontend.

The main contender of the current solution in my mind is to completely split frontend and backend schema and config, essentially having both frontend-config.yaml and backend-config.yaml, as well as frontend-config.d.ts and backend-config.d.ts. That’s the main thing I’m comparing to anyway, but please do add more ideas to the table if possible.

You don’t need to use comments btw, you can use plain old JSON Schema if you want, it’s just not what most people prefer 😅

1. webpack has its own ways of expanding env vars in the bundle and then eliminating dead code with terser. This breaks when all config is parsed from a single variable.

A big benefit of the current config system is that it’s possible to override values per deployment, allowing for example just the app.baseUrl to be tweaked for a preview build. That ofc is not possible if substitution happens at build time.