Project: Backstage (App Definition and Development / Application Definition & Image Build)
File: reading.md

id: reading title: Reading Backstage Configuration description: Documentation on Reading Backstage Configuration There's a common configuration API for by both frontend and backend plugins. An API reference can be found . The configuration API is tailored towards failing fast in case of missing or bad config. That's because configuration errors can always be considered programming mistakes, and will fail deterministically. The methods for reading primitive values are typed, and validate that type at runtime. For example `getNumber()` requires the underlying value to be a number, and there will be no attempt to coerce other types into the desired one. If `getNumber()` receives a string value, it will throw an error, explaining where the bad config came from, and what the desired and actual types where. The backing configuration data is a nested JSON structure, meaning there will be object, within objects, arrays within objects, and so on. There are a couple of different ways to access nested values when reading configuration, but the primary one is to use dot-separated paths. For example, given the following configuration: ```yaml app: baseUrl: http://localhost:3000 ``` We can access the `baseUrl` using `config.getString('app.baseUrl')`. Because of this syntax, configuration keys are not allowed to contain dots. In fact, configuration keys are validated using the following regular expression: `/^(?:[a-z0-9])*$/i`. This basically means that keys must only contain the letters `a` through `z` and digits, in groups separated by dashes or underscores. Additionally, the very first character of each such group must be a letter, not a digit. Another option of accessing the `baseUrl` value is to create a sub-view of the configuration, `config.getConfig('app').getString('baseUrl')`. When reading out single values the dot-path pattern is preferred, but creating sub-views can be useful for when you want to pass on parts of configuration to be read out by a separate function. For example, given something like ```yaml my-plugin: items: a: title: Item A path: /a b: title: Item B path: /b ``` You can get the list of all items using the `.keys()` method, and then pass on each sub-view to be handled individually. ```ts for (const itemKey of config.keys('my-plugin.items')) { const itemConfig = config.getConfig(`my-plugin.items`).getConfig(itemKey); const title = itemConfig.getString('title'); // ... } ``` Another option for iterating through configuration keys is to call `config.get('my-plugin.items')`, which simply returns the JSON structure for that position without any validation. This can be handy to use sometimes, especially if you're passing on config to an external

There's a clear benefit to the sub-view approach though, which is that the user will receive much more detailed and relevant error messages. For example, if `itemConfig.getString('title')` fails in the above example because a boolean was supplied, the user will receive an error message with the full path, e.g. `my-plugin.items.b.title`, as well as the name of the config file with the bad value. Conversely, if you try to access missing fields in raw JSON, you tend to end up with very technical and hard-to-understand type errors from javascript. Note that no matter what method is used for reading out nested config, the same merging rules apply. You will always get the same value for any way of accessing nested config: ```ts // Equivalent as long as a.b.c exists and is a string config.getString('a.b.c'); config.getConfig('a.b').getString('c'); config.get('a').b.c; ``` Reading configuration can be divided into two categories: required, and optional. When reading optional configuration you use the optional methods such as `getOptionalString`. These methods will simply return `undefined` if configuration values are missing, allowing the called to fall back to default values. The optional methods still validate types however, so receiving a string in a call to `config.getOptionalNumber` will still throw an error. A good pattern for reading optional configuration values is to use the `??` operator. For example: ```ts const title = config.getOptionalString('my-plugin.title') ?? 'My Plugin'; ``` To read required configuration, simply use the methods without `Optional`, for example `getString`. These will throw an error if there is no value available. The in the frontend is a . It's accessible as usual via the `configApiRef` exported from `@backstage/core-plugin-api`: ``` import { useApi, configApiRef } from '@backstage/core-plugin-api'; ... const MyReactComponent = (...) => { const config = useApi(configApiRef); ... } ``` Depending on the config api in another API is slightly different though, as the `ConfigApi` implementation is supplied via the App itself and not instantiated like other APIs. See for an example of how this wiring is done. For standalone plugin setups in `dev/index.ts`, register a factory with a statically mocked implementation of the config API. Use the `ConfigReader` from `@backstage/config` to create an instance and register it for the `configApiRef` from `@backstage/core-plugin-api`. In the old backend system plugins, the configuration is passed in via options from the main backend package. See for example . In the new backend system, plugins are able to directly access config through dependencies. You can access config like so, ```ts title="plugins/your-plugin-backend/src/plugin.ts" export const yourPlugin = createBackendPlugin({ pluginId: 'yourPlugin', register(env) { env.registerInit({ deps: { httpRouter: coreServices.httpRouter, logger: coreServices.logger, // highlight-next-line config: coreServices.rootConfig, }, async init({ httpRouter, logger, // highlight-next-line config, }) { // highlight-next-line console.log(config.getOptionalString('backend.test.property')); }, }); }, }); ```