paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 27 Packages Projects Releases Wiki Activity

Merge pull request #30092 from Sarabadu/module-id-validation

Browse Source 
validate plugin and module ids
This commit is contained in:
Patrik Oldsberg
2026-02-02 20:13:35 +01:00
committed by GitHub
parent f9d2fa6d1b 5d71d7e0b4
commit 12ef180a5f
12 changed files with 158 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/odd-lemons-occur.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/frontend-plugin-api': minor
---
Plugin IDs that do not match the standard format are deprecated (letters, digits, and dashes only, starting with a letter). Plugin IDs that do no match this format will be rejected in a future release.
.changeset/slow-numbers-study.md
+7
View File
@@ -0,0 +1,7 @@
---
'@backstage/backend-plugin-api': minor
---
Plugin IDs that do not match the standard format are deprecated (letters, digits, and dashes only, starting with a letter). Plugin IDs that do no match this format will be rejected in a future release.
In addition, plugin IDs that don't match the legacy pattern that also allows underscores, with be rejected.
docs/backend-system/architecture/08-naming-patterns.md
+8 -8
View File
@@ -11,10 +11,10 @@ As a rule, all names should be camel case, with the exceptions of plugin and mod
### Plugins
| Description | Pattern | Examples |
| ----------- | ----------------- | ------------------------------------- |
| export | `<camelId>Plugin` | `catalogPlugin`, `userSettingsPlugin` |
| ID | `'<kebab-id>'` | `'catalog'`, `'user-settings'` |
| Description | Pattern | Examples | Notes |
| ----------- | ----------------- | ------------------------------------- | --------------------------------------------------- |
| export | `<camelId>Plugin` | `catalogPlugin`, `userSettingsPlugin` | |
| ID | `'<kebab-id>'` | `'catalog'`, `'user-settings'` | letters, digits, and dashes, starting with a letter |
Example:
@@ -27,10 +27,10 @@ export const userSettingsPlugin = createBackendPlugin({
### Modules
| Description | Pattern | Examples |
| ----------- | ---------------------------- | ----------------------------------- |
| export | `<pluginId>Module<ModuleId>` | `catalogModuleGithubEntityProvider` |
| ID | `'<module-id>'` | `'github-entity-provider'` |
| Description | Pattern | Examples | Notes |
| ----------- | ---------------------------- | ----------------------------------- | --------------------------------------------------- |
| export | `<pluginId>Module<ModuleId>` | `catalogModuleGithubEntityProvider` | |
| ID | `'<module-id>'` | `'github-entity-provider'` | letters, digits, and dashes, starting with a letter |
Example:
packages/backend-dynamic-feature-service/src/schemas/frontend.ts
+1 -1
View File
@@ -31,7 +31,7 @@ import {
*/
export const dynamicPluginsFrontendSchemas = createBackendModule({
pluginId: 'app',
moduleId: 'core.dynamicplugins.frontendSchemas',
moduleId: 'core-dynamicplugins-frontendSchemas',
register(reg) {
reg.registerInit({
deps: {
packages/backend-plugin-api/src/wiring/constants.ts
+31
View File
@@ -0,0 +1,31 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// NOTE: changing any of these constants need to be reflected in
// @backstage/frontend-plugin-api/src/wiring/constants.ts as well
/**
* The pattern that IDs must match.
*
* @remarks
* ids must only contain the letters `a` through `z` and digits, in groups separated by
* dashes. Additionally, the very first character of the first group
* must be a letter, not a digit
*
* @public
*/
export const ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/i;
export const ID_PATTERN_OLD = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/i;
packages/backend-plugin-api/src/wiring/createBackendModule.test.ts
+17
View File
@@ -15,6 +15,7 @@
*/
import { createServiceRef } from '../services';
import { ID_PATTERN } from './constants';
import { createBackendModule } from './createBackendModule';
import { createExtensionPoint } from './createExtensionPoint';
import { InternalBackendRegistrations } from './types';
@@ -77,4 +78,20 @@ describe('createBackendModule', () => {
expect(plugin.$$type).toEqual('@backstage/BackendFeature');
});
it('should reject modules with invalid moduleId', async () => {
expect(() =>
createBackendModule({
pluginId: 'test',
moduleId: 'invalid:module&id',
register(reg) {
reg.registerInit({
deps: {},
async init() {},
});
},
}),
).toThrow(
`Invalid moduleId 'invalid:module&id' for plugin 'test', must match the pattern ${ID_PATTERN} (letters, digits, and dashes only, starting with a letter)`,
);
});
});
packages/backend-plugin-api/src/wiring/createBackendModule.ts
+12
View File
@@ -15,6 +15,7 @@
*/
import { BackendFeature } from '../types';
import { ID_PATTERN, ID_PATTERN_OLD } from './constants';
import {
BackendModuleRegistrationPoints,
ExtensionPoint,
@@ -55,6 +56,17 @@ export interface CreateBackendModuleOptions {
export function createBackendModule(
options: CreateBackendModuleOptions,
): BackendFeature {
if (!ID_PATTERN.test(options.moduleId)) {
console.warn(
`WARNING: The moduleId '${options.moduleId}' for plugin '${options.pluginId}', will be invalid soon, please change it to match the pattern ${ID_PATTERN} (letters, digits, and dashes only, starting with a letter)`,
);
}
if (!ID_PATTERN_OLD.test(options.moduleId)) {
throw new Error(
`Invalid moduleId '${options.moduleId}' for plugin '${options.pluginId}', must match the pattern ${ID_PATTERN} (letters, digits, and dashes only, starting with a letter)`,
);
}
function getRegistrations() {
const extensionPoints: InternalBackendModuleRegistrationV1_1['extensionPoints'] =
[];
packages/backend-plugin-api/src/wiring/createBackendPlugin.test.ts
+16
View File
@@ -15,6 +15,7 @@
*/
import { createServiceRef } from '../services';
import { ID_PATTERN } from './constants';
import { createBackendPlugin } from './createBackendPlugin';
import { createExtensionPoint } from './createExtensionPoint';
import { InternalBackendRegistrations } from './types';
@@ -90,4 +91,19 @@ describe('createBackendPlugin', () => {
expect(plugin.$$type).toEqual('@backstage/BackendFeature');
});
it('should reject plugins with invalid pluginId', async () => {
expect(() =>
createBackendPlugin({
pluginId: 'test:invalid&id',
register(reg) {
reg.registerInit({
deps: {},
async init() {},
});
},
}),
).toThrow(
`Invalid pluginId 'test:invalid&id', must match the pattern ${ID_PATTERN} (letters, digits, and dashes only, starting with a letter)`,
);
});
});
packages/backend-plugin-api/src/wiring/createBackendPlugin.ts
+12
View File
@@ -22,6 +22,7 @@ import {
InternalBackendPluginRegistrationV1_1,
InternalBackendRegistrations,
} from './types';
import { ID_PATTERN, ID_PATTERN_OLD } from './constants';
/**
* The configuration options passed to {@link createBackendPlugin}.
@@ -50,6 +51,17 @@ export interface CreateBackendPluginOptions {
export function createBackendPlugin(
options: CreateBackendPluginOptions,
): BackendFeature {
if (!ID_PATTERN.test(options.pluginId)) {
console.warn(
`WARNING: The pluginId '${options.pluginId}' will be invalid soon, please change it to match the pattern ${ID_PATTERN} (letters, digits, and dashes only, starting with a letter)`,
);
}
if (!ID_PATTERN_OLD.test(options.pluginId)) {
throw new Error(
`Invalid pluginId '${options.pluginId}', must match the pattern ${ID_PATTERN} (letters, digits, and dashes only, starting with a letter)`,
);
}
function getRegistrations() {
const extensionPoints: InternalBackendPluginRegistrationV1_1['extensionPoints'] =
[];
packages/frontend-plugin-api/src/wiring/constants.ts
+30
View File
@@ -0,0 +1,30 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// NOTE: changing any of these constants need to be reflected in
// @backstage/backend-plugin-api/src/wiring/constants.ts as well
/**
* The pattern that IDs must match.
*
* @remarks
* ids must only contain the letters `a` through `z` and digits, in groups separated by
* dashes. Additionally, the very first character of the first group
* must be a letter, not a digit
*
* @public
*/
export const ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/i;
packages/frontend-plugin-api/src/wiring/createFrontendPlugin.test.ts
+11
View File
@@ -142,6 +142,17 @@ describe('createFrontendPlugin', () => {
expect(String(plugin)).toBe('Plugin{id=test}');
});
it('should warn about invalid plugin IDs', () => {
const consoleWarn = jest
.spyOn(console, 'warn')
.mockImplementation(() => {});
createFrontendPlugin({ pluginId: 'invalid&id' });
expect(consoleWarn).toHaveBeenCalledWith(
expect.stringContaining("The pluginId 'invalid&id' will be invalid soon"),
);
consoleWarn.mockRestore();
});
it('should create a plugin with extension instances', async () => {
const plugin = createFrontendPlugin({
pluginId: 'test',
packages/frontend-plugin-api/src/wiring/createFrontendPlugin.ts
+8
View File
@@ -30,6 +30,7 @@ import { FeatureFlagConfig } from './types';
import { MakeSortedExtensionsMap } from './MakeSortedExtensionsMap';
import { JsonObject } from '@backstage/types';
import { RouteRef, SubRouteRef, ExternalRouteRef } from '../routing';
import { ID_PATTERN } from './constants';
/**
* Information about the plugin.
@@ -208,6 +209,13 @@ export function createFrontendPlugin<
> {
const pluginId = options.pluginId;
if (!ID_PATTERN.test(pluginId)) {
// eslint-disable-next-line no-console
console.warn(
`WARNING: The pluginId '${pluginId}' will be invalid soon, please change it to match the pattern ${ID_PATTERN} (letters, digits, and dashes only, starting with a letter)`,
);
}
const extensions = new Array<Extension<any>>();
const extensionDefinitionsById = new Map<
string,