From 8b1bf6e0692f35da15cdf70bece21b16356ac8c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Thu, 7 Aug 2025 16:57:41 +0200 Subject: [PATCH] elevate app.packages to no longer be experimental MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/open-bottles-film.md | 7 ++ .changeset/solid-ducks-flow.md | 7 ++ .changeset/tame-sloths-boil.md | 5 ++ app-config.yaml | 3 +- docs/frontend-system/architecture/10-app.md | 25 ++++--- .../building-apps/08-migrating.md | 3 +- packages/app-next/app-config.yaml | 3 +- .../build/lib/bundler/packageDetection.ts | 16 ++--- .../templates/next-app/app-config.yaml.hbs | 3 +- packages/frontend-app-api/config.d.ts | 17 +++++ .../frontend-defaults/src/discovery.test.ts | 2 +- packages/frontend-defaults/src/discovery.ts | 16 ++--- .../src/loader.test.tsx | 66 +++++++------------ plugins/api-docs/README-alpha.md | 5 +- plugins/catalog-graph/README-alpha.md | 38 +++++------ plugins/org/README-alpha.md | 5 +- 16 files changed, 110 insertions(+), 111 deletions(-) create mode 100644 .changeset/open-bottles-film.md create mode 100644 .changeset/solid-ducks-flow.md create mode 100644 .changeset/tame-sloths-boil.md diff --git a/.changeset/open-bottles-film.md b/.changeset/open-bottles-film.md new file mode 100644 index 0000000000..68c04f8ada --- /dev/null +++ b/.changeset/open-bottles-film.md @@ -0,0 +1,7 @@ +--- +'@backstage/plugin-catalog-graph': patch +'@backstage/plugin-api-docs': patch +'@backstage/plugin-org': patch +--- + +Updated README instructions for the new frontend system diff --git a/.changeset/solid-ducks-flow.md b/.changeset/solid-ducks-flow.md new file mode 100644 index 0000000000..7828216898 --- /dev/null +++ b/.changeset/solid-ducks-flow.md @@ -0,0 +1,7 @@ +--- +'@backstage/frontend-defaults': patch +'@backstage/frontend-app-api': patch +'@backstage/cli': patch +--- + +Deprecated new frontend system config setting `app.experimental.packages` to just `app.packages`. The old config will continue working for the time being, but may be removed in a future release. diff --git a/.changeset/tame-sloths-boil.md b/.changeset/tame-sloths-boil.md new file mode 100644 index 0000000000..8b718fe970 --- /dev/null +++ b/.changeset/tame-sloths-boil.md @@ -0,0 +1,5 @@ +--- +'@backstage/create-app': patch +--- + +Updated the `app.packages` config setting now that it no longer is experimental diff --git a/app-config.yaml b/app-config.yaml index 910a3e4f99..9c0cb8ef16 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -1,8 +1,7 @@ app: title: Backstage Example App baseUrl: http://localhost:3000 - experimental: - packages: all # ✨ + packages: all # ✨ #datadogRum: # clientToken: '123456789' diff --git a/docs/frontend-system/architecture/10-app.md b/docs/frontend-system/architecture/10-app.md index 3fcfec9e9b..d1ab51d5be 100644 --- a/docs/frontend-system/architecture/10-app.md +++ b/docs/frontend-system/architecture/10-app.md @@ -48,31 +48,28 @@ App feature discovery lets you automatically discover and install features provi Because feature discovery needs to interact with the compilation process, it is only available when using the `@backstage/cli` to build your app. It is hooked into the WebPack compilation process by scanning your app package for compatible dependencies, which are then made part of the app compilation bundle. -Since the `@backstage/cli` is a more stable component than the new frontend system, feature discovery is currently marked as an experimental feature of the CLI and needs to be enabled manually. To enable it, add the following configuration to your `app-config.yaml`: +To enable frontend feature discovery, add the following configuration to your `app-config.yaml`: ```yaml app: - experimental: - packages: all + packages: all ``` This will cause all dependencies in your app package to be installed automatically. If this is not desired, you can use include or exclude filters to narrow down the set of packages: ```yaml app: - experimental: - packages: - # Only the following packages will be included - include: - - '@backstage/plugin-catalog' - - '@backstage/plugin-scaffolder' + packages: + # Only the following packages will be included + include: + - '@backstage/plugin-catalog' + - '@backstage/plugin-scaffolder' --- app: - experimental: - packages: - # All but the following package will be included - exclude: - - '@backstage/plugin-catalog' + packages: + # All but the following package will be included + exclude: + - '@backstage/plugin-catalog' ``` Note that you do not need to manually exclude packages that you also import explicitly in code, since plugin instances are deduplicated by the app. You will never end up with duplicate plugin installations except if they are in fact two different plugin instances with different IDs. diff --git a/docs/frontend-system/building-apps/08-migrating.md b/docs/frontend-system/building-apps/08-migrating.md index a4ed7859f6..e796f64728 100644 --- a/docs/frontend-system/building-apps/08-migrating.md +++ b/docs/frontend-system/building-apps/08-migrating.md @@ -244,8 +244,7 @@ Plugins don't even have to be imported manually after installing their package i ```yaml title="in app-config.yaml" app: # Enabling plugin and override features discovery - experimental: - packages: all # ✨ + packages: all # ✨ ``` ### `featureFlags` diff --git a/packages/app-next/app-config.yaml b/packages/app-next/app-config.yaml index 5665324be6..f83e4d4ba0 100644 --- a/packages/app-next/app-config.yaml +++ b/packages/app-next/app-config.yaml @@ -1,6 +1,5 @@ app: - experimental: - packages: 'all' # ✨ + packages: 'all' # ✨ routes: bindings: diff --git a/packages/cli/src/modules/build/lib/bundler/packageDetection.ts b/packages/cli/src/modules/build/lib/bundler/packageDetection.ts index f69333abb3..df7ca9e77a 100644 --- a/packages/cli/src/modules/build/lib/bundler/packageDetection.ts +++ b/packages/cli/src/modules/build/lib/bundler/packageDetection.ts @@ -32,7 +32,10 @@ interface PackageDetectionConfig { function readPackageDetectionConfig( config: Config, ): PackageDetectionConfig | undefined { - const packages = config.getOptional('app.experimental.packages'); + // The experimental key is deprecated, but supported still for backwards compatibility + const packages = + config.getOptional('app.packages') ?? + config.getOptional('app.experimental.packages'); if (packages === undefined || packages === null) { return undefined; } @@ -40,21 +43,16 @@ function readPackageDetectionConfig( if (typeof packages === 'string') { if (packages !== 'all') { throw new Error( - `Invalid app.experimental.packages mode, got '${packages}', expected 'all'`, + `Invalid app.packages mode, got '${packages}', expected 'all'`, ); } return {}; } if (typeof packages !== 'object' || Array.isArray(packages)) { - throw new Error( - "Invalid config at 'app.experimental.packages', expected object", - ); + throw new Error("Invalid config at 'app.packages', expected object"); } - const packagesConfig = new ConfigReader( - packages, - 'app.experimental.packages', - ); + const packagesConfig = new ConfigReader(packages, 'app.packages'); return { include: packagesConfig.getOptionalStringArray('include'), diff --git a/packages/create-app/templates/next-app/app-config.yaml.hbs b/packages/create-app/templates/next-app/app-config.yaml.hbs index 7688aee89b..b80b980d10 100644 --- a/packages/create-app/templates/next-app/app-config.yaml.hbs +++ b/packages/create-app/templates/next-app/app-config.yaml.hbs @@ -2,8 +2,7 @@ app: title: Scaffolded Backstage App baseUrl: http://localhost:3000 - experimental: - packages: all + packages: all extensions: # Disable the nav items that we're manually rendering in packages/app/src/modules/nav/Sidebar.tsx diff --git a/packages/frontend-app-api/config.d.ts b/packages/frontend-app-api/config.d.ts index 3b86b5c1d4..7032cd378d 100644 --- a/packages/frontend-app-api/config.d.ts +++ b/packages/frontend-app-api/config.d.ts @@ -20,10 +20,27 @@ export interface Config { /** * @visibility frontend * @deepVisibility frontend + * @deprecated This is no longer experimental; use `app.packages` instead. */ packages?: 'all' | { include?: string[]; exclude?: string[] }; }; + /** + * Controls what packages are loaded by the new frontend system. + * + * @remarks + * + * When using the 'all' option, all feature packages that were added as + * dependencies to the app will be loaded automatically. + * + * The `include` and `exclude` options can be used to more finely control + * which individual package names to include or exclude. + * + * @visibility frontend + * @deepVisibility frontend + */ + packages?: 'all' | { include?: string[]; exclude?: string[] }; + routes?: { /** * Maps external route references to regular route references. Both the diff --git a/packages/frontend-defaults/src/discovery.test.ts b/packages/frontend-defaults/src/discovery.test.ts index d1738554a4..b4e595890a 100644 --- a/packages/frontend-defaults/src/discovery.test.ts +++ b/packages/frontend-defaults/src/discovery.test.ts @@ -27,7 +27,7 @@ Object.defineProperty(global, '__@backstage/discovered__', { }); const config = new ConfigReader({ - app: { experimental: { packages: 'all' } }, + app: { packages: 'all' }, }); describe('discoverAvailableFeatures', () => { diff --git a/packages/frontend-defaults/src/discovery.ts b/packages/frontend-defaults/src/discovery.ts index 6da6146389..71d831b58c 100644 --- a/packages/frontend-defaults/src/discovery.ts +++ b/packages/frontend-defaults/src/discovery.ts @@ -26,7 +26,10 @@ interface DiscoveryGlobal { } function readPackageDetectionConfig(config: Config) { - const packages = config.getOptional('app.experimental.packages'); + // The experimental key is deprecated, but supported still for backwards compatibility + const packages = + config.getOptional('app.packages') ?? + config.getOptional('app.experimental.packages'); if (packages === undefined || packages === null) { return undefined; } @@ -34,21 +37,16 @@ function readPackageDetectionConfig(config: Config) { if (typeof packages === 'string') { if (packages !== 'all') { throw new Error( - `Invalid app.experimental.packages mode, got '${packages}', expected 'all'`, + `Invalid app.packages mode, got '${packages}', expected 'all'`, ); } return {}; } if (typeof packages !== 'object' || Array.isArray(packages)) { - throw new Error( - "Invalid config at 'app.experimental.packages', expected object", - ); + throw new Error("Invalid config at 'app.packages', expected object"); } - const packagesConfig = new ConfigReader( - packages, - 'app.experimental.packages', - ); + const packagesConfig = new ConfigReader(packages, 'app.packages'); return { include: packagesConfig.getOptionalStringArray('include'), diff --git a/packages/frontend-dynamic-feature-loader/src/loader.test.tsx b/packages/frontend-dynamic-feature-loader/src/loader.test.tsx index 4b872a5414..b2f6486766 100644 --- a/packages/frontend-dynamic-feature-loader/src/loader.test.tsx +++ b/packages/frontend-dynamic-feature-loader/src/loader.test.tsx @@ -127,10 +127,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -204,10 +202,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -330,10 +326,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -447,10 +441,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -540,10 +532,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -604,10 +594,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -653,10 +641,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -759,10 +745,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -889,10 +873,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -1002,10 +984,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { @@ -1112,10 +1092,8 @@ describe('dynamicFrontendFeaturesLoader', () => { config: mockApis.config({ data: { app: { - experimental: { - packages: { - include: [], - }, + packages: { + include: [], }, }, backend: { diff --git a/plugins/api-docs/README-alpha.md b/plugins/api-docs/README-alpha.md index fef8d491b8..1c30d62cd4 100644 --- a/plugins/api-docs/README-alpha.md +++ b/plugins/api-docs/README-alpha.md @@ -68,9 +68,8 @@ To link that a component provides or consumes an API, see the [`providesApis`](h ```yaml # app-config.yaml app: - experimental: - # Auto discovering all plugins extensions - packages: all + # Auto discovering all plugins extensions + packages: all extensions: # Enabling some entity cards # The cards will be displayed in the same order it appears in this setting list diff --git a/plugins/catalog-graph/README-alpha.md b/plugins/catalog-graph/README-alpha.md index 945cdace71..bc5cea3fd1 100644 --- a/plugins/catalog-graph/README-alpha.md +++ b/plugins/catalog-graph/README-alpha.md @@ -36,18 +36,18 @@ This plugin installation requires the following steps: 1. Add the `@backstage/catalog-graph` dependency to your app `package.json` file and install it; 2. In your application's configuration file, enable the catalog entity relations graphic card extension so that the card begins to be presented on the catalog entity page: -```yaml -# app-config.yaml -app: - experimental: - # Auto discovering all plugins extensions - packages: all - extensions: - # This is required because the card is not enable by default once you install the plugin - - entity-card:catalog-graph/relations -``` + ```yaml + # app-config.yaml + app: + # Auto discovering all plugins extensions + packages: all + extensions: + # This is required because the card is not enable by default once you install the plugin + - entity-card:catalog-graph/relations + ``` 3. Then start the app, navigate to an entity's page and see the Relations graph there; + 4. By clicking on the "View Graph" card action, you will be redirected to the catalog entity relations page. ## Customization @@ -64,11 +64,10 @@ _Enabling auto discovering the plugin extensions in production_ # app-config.production.yaml # Overriding configurations for the local production environment app: - experimental: - packages: - # Only the following packages will be included - include: - - '@backstage/plugin-catalog-graph' + packages: + # Only the following packages will be included + include: + - '@backstage/plugin-catalog-graph' ``` _Disabling auto discovering the plugin extensions in development_ @@ -77,11 +76,10 @@ _Disabling auto discovering the plugin extensions in development_ # app-config.local.yaml # Overriding configurations for the local development environment app: - experimental: - packages: - # All but the following package will be included - exclude: - - '@backstage/plugin-catalog-graph' + packages: + # All but the following package will be included + exclude: + - '@backstage/plugin-catalog-graph' ``` For more options of package configurations, see [this](https://backstage.io/docs/frontend-system/architecture/app/#feature-discovery) documentation. diff --git a/plugins/org/README-alpha.md b/plugins/org/README-alpha.md index 30c4bce1c2..35258800f2 100644 --- a/plugins/org/README-alpha.md +++ b/plugins/org/README-alpha.md @@ -48,9 +48,8 @@ And below is an example of how a user page looks with the user profile and owner ```yaml # app-config.yaml app: - experimental: - # Auto discovering all plugins extensions - packages: all + # Auto discovering all plugins extensions + packages: all extensions: # Enabling the org plugin cards - entity-card:org/group-profile