docs/releases/v1.44.0-next.2-changelog.md
Upgrade Helper: https://backstage.github.io/upgrade-helper/?to=1.44.0-next.2
readDurationFromConfig support both ISO and ms formats as well, to make it easier to enter time as an end userConfigReader now treats null values as present but explicitly undefined, meaning it will not fall back to the next level of configuration.ConfigReader now treats null values as present but explicitly undefined, meaning it will not fall back to the next level of configuration.readDurationFromConfig function@types/node dependency@types/node dependencyreadDurationFromConfig function"true" 1 on and y will become true when using getBoolean and the opposites false.
This happens particularly when such parameters are used with environmental substitution as environment variables are always strings."true" 1 on and y will become true when using getBoolean and the opposites false.
This happens particularly when such parameters are used with environmental substitution as environment variables are always strings.@types/jest.@types/jest.@types/node to ^16.0.0.@types/node to ^16.0.0.backstage.role to package.jsonf685e1398f: Loading of app configurations now reference the @deprecated construct from
JSDoc to determine if a property in-use has been deprecated. Users are notified
of deprecated keys in the format:
The configuration key 'catalog.processors.githubOrg' of app-config.yaml is deprecated and may be removed soon. Configure a GitHub integration instead.
When the withDeprecatedKeys option is set to true in the process method
of loadConfigSchema, the user will be notified that deprecated keys have been
identified in their app configuration.
The backend-common and plugin-app-backend packages have been updated to set
withDeprecatedKeys to true so that users are notified of deprecated settings
by default.
f685e1398f: Loading of app configurations now reference the @deprecated construct from
JSDoc to determine if a property in-use has been deprecated. Users are notified
of deprecated keys in the format:
The configuration key 'catalog.processors.githubOrg' of app-config.yaml is deprecated and may be removed soon. Configure a GitHub integration instead.
When the withDeprecatedKeys option is set to true in the process method
of loadConfigSchema, the user will be notified that deprecated keys have been
identified in their app configuration.
The backend-common and plugin-app-backend packages have been updated to set
withDeprecatedKeys to true so that users are notified of deprecated settings
by default.
ConfigReader#get method now always returns a deep clone of the configuration data.@backstage/types package. Initially, this means using the Observable and Json* types from there. The types also remain in their old places but deprecated, and will be removed in a future release.lodash to remediate SNYK-JS-LODASH-590103 security vulnerabilityConfig interface and mark types as public.Config interface to have an optional subscribe method that can be used be notified of updates to the configuration.json-schema dependency from 0.2.5 to 0.3.0.a1f5e6545: Adds an optional type to config.get & config.getOptional. This avoids the need for casting. For example:
const config = useApi(configApiRef);
const myConfig = config.get<SomeTypeDefinition>('myPlugin.complexConfig');
// vs
const myConfig config.get('myPlugin.complexConfig') as SomeTypeDefinition;
BACKSTAGE_ENV for loading environment specific config filesBACKSTAGE_ENV for loading environment specific config files$file, $env, and $include. Any other key that begins with a `# @backstage/config-loader will now be passed through as is.@types/minimist to devDependencies$file, $env, and $include. Any other key that begins with a `# @backstage/config-loader will now be passed through as is.require for lazy-loading dependency.require for lazy-loading dependency.@backstage/backend-common from schema collection if @backstage/backend-defaults is present@backstage/backend-common from schema collection if @backstage/backend-defaults is presenttypescript-json-schema to ^0.65.0.typescript-json-schema to ^0.65.0.ConfigSources that enables configuration of parsing logic. Previously limited to yaml, these ConfigSources now allow for a multitude of parsing options (e.g. JSON).env option of ConfigSources.default now correctly allows undefined members.allowMissingDefaultConfig option to ConfigSources.default and
ConfigSources.defaultForTargets, which results in omission of a ConfigSource
for the default app-config.yaml configuration file if it's not present.ConfigSources that enables configuration of parsing logic. Previously limited to yaml, these ConfigSources now allow for a multitude of parsing options (e.g. JSON).env option of ConfigSources.default now correctly allows undefined members.allowMissingDefaultConfig option to ConfigSources.default and
ConfigSources.defaultForTargets, which results in omission of a ConfigSource
for the default app-config.yaml configuration file if it's not present.2ce31b3: The default environment variable substitution function will now trim whitespace characters from the substituted value. This alleviates bugs where whitespace characters are mistakenly included in environment variables.
If you depend on the old behavior, you can override the default substitution function with your own, for example:
ConfigSources.default({
substitutionFunc: async name => process.env[name],
});
99bab65: Support parameter substitution for environment variables
null values read from configuration files in configuration data, rather than treating them as an absence of config.null values read from configuration files in configuration data, rather than treating them as an absence of config.fs-extra to ^11.2.0.
Updated dependency @types/fs-extra to ^11.0.0.typescript-json-schema to ^0.63.0.mock-fs dev dependency.mock-fs dev dependency.TransformFunc contextTransformFunc contexttypescript-json-schema to ^0.62.0.typescript-json-schema to ^0.61.0.FileConfigSource will now retry file reading after a short delay if it reads an empty file. This is to avoid flakiness during watch mode where change events can trigger before the file content has been written.watch option to configuration loaders that can be used to disable file watching by setting it to false.typescript-json-schema to ^0.61.0.watch option to configuration loaders that can be used to disable file watching by setting it to false.FileConfigSource will now retry file reading after a short delay if it reads an empty file. This is to avoid flakiness during watch mode where change events can trigger before the file content has been written.9606ba0939e6: Deep visibility now also applies to values that are not covered by the configuration schema.
For example, given the following configuration schema:
// plugins/a/config.schema.ts
export interface Config {
/** @deepVisibility frontend */
a?: unknown;
}
// plugins/a/config.schema.ts
export interface Config {
a?: {
b?: string;
};
}
All values under a are now visible to the frontend, while previously only a and a/b would've been visible.
@types/node dependency@types/node dependency9606ba0939e6: Deep visibility now also applies to values that are not covered by the configuration schema.
For example, given the following configuration schema:
// plugins/a/config.schema.ts
export interface Config {
/** @deepVisibility frontend */
a?: unknown;
}
// plugins/a/config.schema.ts
export interface Config {
a?: {
b?: string;
};
}
All values under a are now visible to the frontend, while previously only a and a/b would've been visible.
2f1859585998: Loading invalid TypeScript configuration schemas will now throw an error rather than silently being ignored.
In particular this includes defining any additional types other than Config in the schema file, or use of unsupported types such as Record or Partial.
cd514545d1d0: Adds a new deepVisibility schema keyword that sets child visibility recursively to the defined value, respecting preexisting values or child deepVisibility.
Example usage:
export interface Config {
/**
* Enforces a default of `secret` instead of `backend` for this object.
* @deepVisibility secret
*/
mySecretProperty: {
type: 'object';
properties: {
secretValue: {
type: 'string';
};
verySecretProperty: {
type: 'string';
};
};
};
}
Example of a schema that would not be allowed:
export interface Config {
/**
* Set the top level property to secret, enforcing a default of `secret` instead of `backend` for this object.
* @deepVisibility secret
*/
mySecretProperty: {
type: 'object';
properties: {
frontendUrl: {
/**
* We can NOT override the visibility to reveal a property to the front end.
* @visibility frontend
*/
type: 'string';
};
verySecretProperty: {
type: 'string';
};
};
};
}
2f1859585998: Loading invalid TypeScript configuration schemas will now throw an error rather than silently being ignored.
In particular this includes defining any additional types other than Config in the schema file, or use of unsupported types such as Record or Partial.
cd514545d1d0: Adds a new deepVisibility schema keyword that sets child visibility recursively to the defined value, respecting preexisting values or child deepVisibility.
Example usage:
export interface Config {
/**
* Enforces a default of `secret` instead of `backend` for this object.
* @deepVisibility secret
*/
mySecretProperty: {
type: 'object';
properties: {
secretValue: {
type: 'string';
};
verySecretProperty: {
type: 'string';
};
};
};
}
Example of a schema that would not be allowed:
export interface Config {
/**
* Set the top level property to secret, enforcing a default of `secret` instead of `backend` for this object.
* @deepVisibility secret
*/
mySecretProperty: {
type: 'object';
properties: {
frontendUrl: {
/**
* We can NOT override the visibility to reveal a property to the front end.
* @visibility frontend
*/
type: 'string';
};
verySecretProperty: {
type: 'string';
};
};
};
}
/ in the key were incorrectly handled.durationToMilliseconds from @backstage/types instead of our own/ in the key were incorrectly handled.201206132da: Introduced a new config source system to replace loadConfig. There is a new ConfigSource interface along with utilities provided by ConfigSources, as well as a number of built-in configuration source implementations. The new system is more flexible and makes it easier to create new and reusable sources of configuration, such as loading configuration from secret providers.
The following is an example of how to load configuration using the default behavior:
const source = ConfigSources.default({
argv: options?.argv,
remote: options?.remote,
});
const config = await ConfigSources.toConfig(source);
The ConfigSource interface looks like this:
export interface ConfigSource {
readConfigData(options?: ReadConfigDataOptions): AsyncConfigSourceIterator;
}
It is best implemented using an async iterator:
class MyConfigSource implements ConfigSource {
async *readConfigData() {
yield {
config: [
{
context: 'example',
data: { backend: { baseUrl: 'http://localhost' } },
},
],
};
}
}
noUndeclaredProperties option to SchemaLoader to support enforcing that there are no extra keys when verifying config.201206132da: Introduced a new config source system to replace loadConfig. There is a new ConfigSource interface along with utilities provided by ConfigSources, as well as a number of built-in configuration source implementations. The new system is more flexible and makes it easier to create new and reusable sources of configuration, such as loading configuration from secret providers.
The following is an example of how to load configuration using the default behavior:
const source = ConfigSources.default({
argv: options?.argv,
remote: options?.remote,
});
const config = await ConfigSources.toConfig(source);
The ConfigSource interface looks like this:
export interface ConfigSource {
readConfigData(options?: ReadConfigDataOptions): AsyncConfigSourceIterator;
}
It is best implemented using an async iterator:
class MyConfigSource implements ConfigSource {
async *readConfigData() {
yield {
config: [
{
context: 'example',
data: { backend: { baseUrl: 'http://localhost' } },
},
],
};
}
}
c791fcd96b9: Configuration validation is now more permissive when it comes to config whose values are string but whose schemas declare them to be boolean or number.
For example, configuration was previously marked invalid when a string 'true' was set on a property expecting type boolean or a string '146' was set on a property expecting type number (as when providing configuration via variable substitution sourced from environment variables). Now, such configurations will be considered valid and their values will be coerced to the right type at read-time.
msw to ^1.0.0.msw to ^1.0.0.msw to ^0.49.0.typescript-json-schema to ^0.55.0.typescript-json-schema to ^0.55.0.msw to ^0.49.0.@types/jest.msw to ^0.47.0.msw to ^0.46.0.msw to ^0.45.0.@types/jest.msw to ^0.47.0.msw to ^0.46.0.msw to ^0.45.0.$file placeholder will trim the whitespaces and newline characters from the end of the file it reads.msw to ^0.43.0.yaml to ^2.0.0.msw to ^0.44.0.typescript-json-schema to ^0.54.0.msw to ^0.43.0.yaml to ^2.0.0.typescript-json-schema to ^0.54.0.msw to ^0.41.0.msw to ^0.41.0.fs-extra to 10.1.0.fs-extra to 10.1.0.ignoreSchemaErrors to schema.process.ajv from 7.0.3 to 8.10.0@types/node v16ignoreSchemaErrors to schema.process.@types/node v16ajv from 7.0.3 to 8.10.0typescript-json-schema dependency that is used during schema collection is now lazy loaded, as it eagerly loads in the TypeScript compiler.typescript-json-schema from 0.52.0 to 0.53.0fs-extra from 9.1.0 to 10.0.1fs-extra from 9.1.0 to 10.0.1node-fetch to version 2.6.7 and cross-fetch to version 3.1.5backstage.role to package.jsonf685e1398f: Loading of app configurations now reference the @deprecated construct from
JSDoc to determine if a property in-use has been deprecated. Users are notified
of deprecated keys in the format:
The configuration key 'catalog.processors.githubOrg' of app-config.yaml is deprecated and may be removed soon. Configure a GitHub integration instead.
When the withDeprecatedKeys option is set to true in the process method
of loadConfigSchema, the user will be notified that deprecated keys have been
identified in their app configuration.
The backend-common and plugin-app-backend packages have been updated to set
withDeprecatedKeys to true so that users are notified of deprecated settings
by default.
Updated dependencies
f685e1398f: Loading of app configurations now reference the @deprecated construct from
JSDoc to determine if a property in-use has been deprecated. Users are notified
of deprecated keys in the format:
The configuration key 'catalog.processors.githubOrg' of app-config.yaml is deprecated and may be removed soon. Configure a GitHub integration instead.
When the withDeprecatedKeys option is set to true in the process method
of loadConfigSchema, the user will be notified that deprecated keys have been
identified in their app configuration.
The backend-common and plugin-app-backend packages have been updated to set
withDeprecatedKeys to true so that users are notified of deprecated settings
by default.
Updated dependencies
typescript-json-schema from ^0.51.0 to ^0.52.0.env from LoadConfigOptions and associated testsconfigPaths as it has been superseded by configTargetscross-fetch vs node-fetch in frontend vs backend packages, and remove some unnecessary imports of either one of them1e99c73c75: Update loadConfig to return LoadConfigResult instead of an array of AppConfig.
This function is primarily used internally by other config loaders like loadBackendConfig which means no changes are required for most users.
If you use loadConfig directly you will need to update your usage from:
- const appConfigs = await loadConfig(options)
+ const { appConfigs } = await loadConfig(options)
@backstage/typestypescript-json-schema from 0.50.1 to 0.51.0EnvFunc public export. Its only usage was to be passed in to LoadConfigOptions.experimentalEnvFunc. If you were using this type, add a definition in your own project instead with the signature (name: string) => Promise<string | undefined>.devDependencies and optionalDependencies in the detection of Backstage packages when collecting configuration schema.watch options to loadConfig.filteredKeys property when processing configuration with a schema.[email protected] as that seemed to have broken all installs inexplicably.typescript-json-schema instead. This should again allow the usage of @items.visibility <value> to set the visibility of array items.yarn link or running the CLI in other directories and improve the experience for local backstage development.4.3.json-schema dependency from 0.2.5 to 0.3.0.82c66b8cd: Fix bug where ${...} was not being escaped to ${...}
Add support for environment variable substitution in $include, $file and
$env transform values.
${..}) already
supported outside of the various include transforms.${...} in your include transform values,
you will need to escape the substitution by using ${...} instead to maintain
the same behavior.config-loader to ajv 7, to enable v7 feature use elsewhere$data placeholder.$include placeholder. Meaning that for example for example $env includes will be processed as usual in included files.ef7957be4: Added support for environment variable substitutions in string configuration values using a ${VAR} placeholder. All environment variables must be available, or the entire expression will be evaluated to undefined. To escape a substitution, use ${...}, which will end up as ${...}.
For example:
app:
baseUrl: https://${BASE_HOST}
ad5c56fd9: Deprecate $data and replace it with $include which allows for any type of json value to be read from external files. In addition, $include can be used without a path, which causes the value at the root of the file to be loaded.
Most usages of $data can be directly replaced with $include, except if the referenced value is not a string, in which case the value needs to be changed. For example:
# app-config.yaml
foo:
$data: foo.yaml#myValue # replacing with $include will turn the value into a number
$data: bar.yaml#myValue # replacing with $include is safe
# foo.yaml
myValue: 0xf00
# bar.yaml
myValue: bar
4e7091759: Fix typo of "visibility" in config schema reference
If you have defined a config element named visiblity, you
will need to fix the spelling to visibility. For more info,
see https://backstage.io/docs/conf/defining#visibility.
1722cb53c: Added support for loading and validating configuration schemas, as well as declaring config visibility through schemas.
The new loadConfigSchema function exported by @backstage/config-loader allows for the collection and merging of configuration schemas from all nearby dependencies of the project.
A configuration schema is declared using the https://backstage.io/schema/config-v1 JSON Schema meta schema, which is based on draft07. The only difference to the draft07 schema is the custom visibility keyword, which is used to indicate whether the given config value should be visible in the frontend or not. The possible values are frontend, backend, and secret, where backend is the default. A visibility of secret has the same scope at runtime, but it will be treated with more care in certain contexts, and defining both frontend and secret for the same value in two different schemas will result in an error during schema merging.
Packages that wish to contribute configuration schema should declare it in a root "configSchema" field in package.json. The field can either contain an inlined JSON schema, or a relative path to a schema file. Schema files can be in either .json or .d.ts format.
TypeScript configuration schema files should export a single Config type, for example:
export interface Config {
app: {
/**
* Frontend root URL
* @visibility frontend
*/
baseUrl: string;
};
}
8c2b76e45: BREAKING CHANGE
The existing loading of additional config files like app-config.development.yaml using APP_ENV or NODE_ENV has been removed.
Instead, the CLI and backend process now accept one or more --config flags to load config files.
Without passing any flags, app-config.yaml and, if it exists, app-config.local.yaml will be loaded.
If passing any --config <path> flags, only those files will be loaded, NOT the default app-config.yaml one.
The old behaviour of for example APP_ENV=development can be replicated using the following flags:
--config ../../app-config.yaml --config ../../app-config.development.yaml
ce5512bc0: Added support for new shorthand when defining secrets, where $env: ENV can be used instead of $secret: { env: ENV } etc.
externalTokenHandlersServiceRef to allow custom external token validations/mui-to-bui that converts an existing MUI v5 theme into Backstage UI (BUI) CSS variables, with live preview and copy/download.ab96bb7: Added a new --entrypoint option to the package start command, which allows you to specify a custom entry directory/file for development applications. This is particularly useful when maintaining separate dev apps for different versions of your plugin (e.g., stable and alpha).
Example usage:
Consider the following plugin dev folder structure:
dev/
index.tsx
alpha/
index.ts
yarn package start command uses the dev/ folder as the entry point and executes dev/index.tsx file;yarn package start --entrypoint dev/alpha will instead use dev/alpha/ as the entry point and execute dev/alpha/index.ts file.UnifiedThemeProvider now coordinates theme attributes on the document body in case multiple theme providers are rendered.6493c98: Log before provider-orphaning eviction happens
77516c5: Added new catalog:validate-entity action to actions registry.
This action can be used to validate entities against the software catalog.
This is useful for validating catalog-info.yaml file changes locally using the
Backstage MCP server.
initialRelationAggregation and showAggregateMembersToggle options to EntityMembersListCard as well to EntityOwnershipCard