@n8n/frontend-module-sdk 0.6.2 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@n8n/frontend-module-sdk",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "main": "src/index.ts",
   "import": "src/index.ts",
   "exports": {
@@ -10,8 +10,8 @@
   "dependencies": {
     "vue": "^3.5.13",
     "vue-router": "^4.5.0",
-    "@n8n/design-system": "2.35.2",
-    "@n8n/api-types": "1.36.2"
+    "@n8n/api-types": "1.37.0",
+    "@n8n/design-system": "2.36.0"
   },
   "devDependencies": {
     "typescript": "6.0.2",
@@ -20,8 +20,8 @@
     "vitest": "^4.1.9",
     "vue-tsc": "^2.2.8",
     "@n8n/eslint-config": "0.0.1",
-    "@n8n/typescript-config": "1.10.0",
-    "@n8n/vitest-config": "1.21.0"
+    "@n8n/vitest-config": "1.21.0",
+    "@n8n/typescript-config": "1.10.0"
   },
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://n8n.io",

package/src/index.ts

@@ -1,5 +1,7 @@
 export type * from './types';
 
+export { assertUniqueRouteNames } from './routeNames';
+
 export * as modalRegistry from './registries/modalRegistry';
 export * from './registries/resourceRegistry';
 export * as pushHandlerRegistry from './registries/pushHandlerRegistry';

package/src/registries/commandRegistry.test.ts

@@ -30,16 +30,29 @@ describe('commandRegistry', () => {
 		expect(commandRegistry.getAll()).toEqual([commandA, commandB]);
 	});
 
-	it('should warn and skip when an id is registered twice', () => {
+	it('should warn and skip when a different command claims the id', () => {
 		const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
 		commandRegistry.register(commandA);
-		commandRegistry.register(commandA);
+		commandRegistry.register({ ...commandA, title: 'Impostor' });
 
 		expect(consoleSpy).toHaveBeenCalledWith(
 			'Command with id "cmd-a" is already registered. Skipping.',
 		);
-		expect(commandRegistry.getAll()).toHaveLength(1);
+		expect(commandRegistry.getAll()).toEqual([commandA]);
+
+		consoleSpy.mockRestore();
+	});
+
+	// A re-login replays the manifest, so the same definitions arrive twice.
+	it('should re-register the same command silently', () => {
+		const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+		commandRegistry.register(commandA);
+		commandRegistry.register(commandA);
+
+		expect(consoleSpy).not.toHaveBeenCalled();
+		expect(commandRegistry.getAll()).toEqual([commandA]);
 
 		consoleSpy.mockRestore();
 	});

package/src/registries/commandRegistry.ts

@@ -13,8 +13,13 @@ function notifyListeners(): void {
 }
 
 export function register(command: CommandBarEntry): void {
-	if (commands.has(command.id)) {
-		console.warn(`Command with id "${command.id}" is already registered. Skipping.`);
+	const existing = commands.get(command.id);
+	if (existing) {
+		// Same definition replayed by a re-login is a no-op; a different one
+		// claiming a taken id is the real collision.
+		if (existing !== command) {
+			console.warn(`Command with id "${command.id}" is already registered. Skipping.`);
+		}
 		return;
 	}
 	commands.set(command.id, command);

package/src/registries/modalRegistry.test.ts

@@ -49,20 +49,45 @@ describe('modalRegistry', () => {
 			expect(modalRegistry.getKeys()).toHaveLength(2);
 		});
 
-		it('should warn and skip registration if modal key already exists', () => {
+		it('should warn and skip registration if a different modal claims the key', () => {
 			const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
 			modalRegistry.register(mockModal1);
-			modalRegistry.register(mockModal1);
+			modalRegistry.register({ ...mockModal1, component: mockComponent2 });
 
 			expect(consoleSpy).toHaveBeenCalledWith(
 				'Modal with key "test-modal-1" is already registered. Skipping.',
 			);
 			expect(modalRegistry.getKeys()).toHaveLength(1);
+			expect(modalRegistry.get('test-modal-1')?.component).toBe(mockComponent1);
 
 			consoleSpy.mockRestore();
 		});
 
+		// A re-login replays the manifest, so the same definitions arrive twice.
+		it('should re-register the same definition silently', () => {
+			const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+			modalRegistry.register(mockModal1);
+			modalRegistry.register(mockModal1);
+
+			expect(consoleSpy).not.toHaveBeenCalled();
+			expect(modalRegistry.get('test-modal-1')).toBe(mockModal1);
+			expect(modalRegistry.getKeys()).toHaveLength(1);
+
+			consoleSpy.mockRestore();
+		});
+
+		it('should not notify listeners when the same definition is re-registered', () => {
+			modalRegistry.register(mockModal1);
+			const listener = vi.fn();
+			modalRegistry.subscribe(listener);
+
+			modalRegistry.register(mockModal1);
+
+			expect(listener).not.toHaveBeenCalled();
+		});
+
 		it('should notify listeners when a modal is registered', () => {
 			const listener = vi.fn();
 			modalRegistry.subscribe(listener);

package/src/registries/modalRegistry.ts

@@ -22,8 +22,14 @@ function notifyListeners(): void {
 }
 
 export function register(modal: ModalDefinition): void {
-	if (modals.has(modal.key)) {
-		console.warn(`Modal with key "${modal.key}" is already registered. Skipping.`);
+	const existing = modals.get(modal.key);
+	if (existing) {
+		// Replaying the same definition is how a re-login re-runs registration —
+		// a no-op, not a collision. Only a different definition claiming a taken
+		// key is worth warning about.
+		if (existing !== modal) {
+			console.warn(`Modal with key "${modal.key}" is already registered. Skipping.`);
+		}
 		return;
 	}
 

package/src/registries/pushHandlerRegistry.test.ts

@@ -50,6 +50,21 @@ describe('pushHandlerRegistry', () => {
 		consoleSpy.mockRestore();
 	});
 
+	// A re-login replays the manifest, so the same handlers arrive twice.
+	it('should re-register the same handler silently', () => {
+		const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+		const handler = vi.fn();
+		const handlers: ModulePushHandlers = { workflowActivated: handler };
+
+		pushHandlerRegistry.registerAll(handlers);
+		pushHandlerRegistry.registerAll(handlers);
+
+		expect(consoleSpy).not.toHaveBeenCalled();
+		expect(pushHandlerRegistry.get('workflowActivated')).toBe(handler);
+
+		consoleSpy.mockRestore();
+	});
+
 	it('should register every entry in a module pushHandlers map', () => {
 		const activated = vi.fn();
 		const deactivated = vi.fn();

package/src/registries/pushHandlerRegistry.ts

@@ -7,8 +7,13 @@ import type { ModulePushHandler, ModulePushHandlers } from '../types/push';
 const handlers = new Map<PushType, ModulePushHandler>();
 
 export function register(type: PushType, handler: ModulePushHandler): void {
-	if (handlers.has(type)) {
-		console.warn(`Push handler for type "${type}" is already registered. Skipping.`);
+	const existing = handlers.get(type);
+	if (existing) {
+		// Same handler replayed by a re-login is a no-op; a different one
+		// claiming a taken type is the real collision.
+		if (existing !== handler) {
+			console.warn(`Push handler for type "${type}" is already registered. Skipping.`);
+		}
 		return;
 	}
 	handlers.set(type, handler);

package/src/routeNames.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import { createMemoryHistory, createRouter, type RouteRecordRaw } from 'vue-router';
+
+import { assertUniqueRouteNames } from './routeNames';
+import type { FrontendModuleDescription } from './types/descriptor';
+
+const component = async () => await Promise.resolve({});
+
+const moduleWith = (id: string, routes: RouteRecordRaw[]): FrontendModuleDescription => ({
+	id,
+	name: id,
+	description: '',
+	icon: 'box',
+	routes,
+});
+
+const route = (name: string, children?: RouteRecordRaw[]): RouteRecordRaw =>
+	({ path: `/${name.toLowerCase()}`, name, component, children }) as RouteRecordRaw;
+
+/** A router holding the given routes, standing in for the shell's own. */
+const shellRouter = (routes: RouteRecordRaw[] = []) =>
+	createRouter({ history: createMemoryHistory(), routes });
+
+describe('assertUniqueRouteNames', () => {
+	it('should accept modules with distinct route names', () => {
+		expect(() =>
+			assertUniqueRouteNames(
+				[
+					moduleWith('otel', [route('SettingsOpenTelemetryView')]),
+					moduleWith('mcp', [route('McpSettings')]),
+				],
+				shellRouter(),
+			),
+		).not.toThrow();
+	});
+
+	it('should accept modules that declare no routes', () => {
+		expect(() =>
+			assertUniqueRouteNames([{ id: 'a', name: 'a', description: '', icon: 'box' }], shellRouter()),
+		).not.toThrow();
+	});
+
+	it('should throw and name both modules when two claim the same route name', () => {
+		expect(() =>
+			assertUniqueRouteNames(
+				[moduleWith('otel', [route('Shared')]), moduleWith('insights', [route('Shared')])],
+				shellRouter(),
+			),
+		).toThrow(
+			'Duplicate route name "Shared" declared by module "insights" — already taken by module "otel".',
+		);
+	});
+
+	it('should throw when one module declares the same route name twice', () => {
+		expect(() =>
+			assertUniqueRouteNames([moduleWith('otel', [route('Twice'), route('Twice')])], shellRouter()),
+		).toThrow(
+			'Duplicate route name "Twice" declared by module "otel" — already taken by module "otel".',
+		);
+	});
+
+	it('should detect a collision between a nested child route and a top-level route', () => {
+		expect(() =>
+			assertUniqueRouteNames(
+				[
+					moduleWith('chat', [route('ChatView', [route('Nested')])]),
+					moduleWith('agents', [route('Nested')]),
+				],
+				shellRouter(),
+			),
+		).toThrow(
+			'Duplicate route name "Nested" declared by module "agents" — already taken by module "chat".',
+		);
+	});
+
+	it('should ignore unnamed routes, which vue-router matches by path only', () => {
+		const unnamed = { path: '/a', component } as RouteRecordRaw;
+
+		expect(() =>
+			assertUniqueRouteNames(
+				[moduleWith('a', [unnamed]), moduleWith('b', [unnamed])],
+				shellRouter(),
+			),
+		).not.toThrow();
+	});
+
+	describe('against the shell', () => {
+		it('should throw when a module claims a name the shell already registered', () => {
+			expect(() =>
+				assertUniqueRouteNames(
+					[moduleWith('otel', [route('Workflows')])],
+					shellRouter([route('Workflows')]),
+				),
+			).toThrow(
+				'Duplicate route name "Workflows" declared by module "otel" — already taken by the app shell.',
+			);
+		});
+
+		it('should throw when a module claims the name of a nested shell route', () => {
+			expect(() =>
+				assertUniqueRouteNames(
+					[moduleWith('otel', [route('ExecutionPreview')])],
+					shellRouter([route('WorkflowExecutions', [route('ExecutionPreview')])]),
+				),
+			).toThrow(
+				'Duplicate route name "ExecutionPreview" declared by module "otel" — already taken by the app shell.',
+			);
+		});
+
+		it('should report the shell as the owner even when another module also wants the name', () => {
+			expect(() =>
+				assertUniqueRouteNames(
+					[moduleWith('otel', [route('Settings')]), moduleWith('mcp', [route('Settings')])],
+					shellRouter([route('Settings')]),
+				),
+			).toThrow(
+				'Duplicate route name "Settings" declared by module "otel" — already taken by the app shell.',
+			);
+		});
+
+		it('should accept module names that no shell route uses', () => {
+			expect(() =>
+				assertUniqueRouteNames(
+					[moduleWith('otel', [route('SettingsOpenTelemetryView')])],
+					shellRouter([route('Settings'), route('Workflows')]),
+				),
+			).not.toThrow();
+		});
+	});
+});

package/src/routeNames.ts

@@ -0,0 +1,54 @@
+import type { Router, RouteRecordRaw } from 'vue-router';
+
+import type { FrontendModuleDescription } from './types/descriptor';
+
+const SHELL_OWNER = 'the app shell';
+
+function* declaredRouteNames(routes: RouteRecordRaw[]): Generator<string | symbol> {
+	for (const route of routes) {
+		if (route.name !== undefined && route.name !== null) {
+			yield route.name;
+		}
+		if (route.children) {
+			yield* declaredRouteNames(route.children);
+		}
+	}
+}
+
+/**
+ * Throws when a module claims a route name that is already taken, by the shell
+ * or by another module.
+ *
+ * Route names are global to the router, and `router.addRoute` replaces a
+ * duplicate without warning — the losing route simply stops resolving. A central
+ * `VIEWS` enum kept every name unique, shell and module alike, because they were
+ * all members of one enum. Module-owned name constants are the better contract,
+ * but they scatter that check, so it is restored here.
+ *
+ * Call this before registering any module route. The shell's names are read from
+ * `router`, so a module route added earlier would be counted as pre-existing
+ * rather than reported.
+ */
+export function assertUniqueRouteNames(modules: FrontendModuleDescription[], router: Router): void {
+	const owners = new Map<string | symbol, string>();
+
+	for (const { name } of router.getRoutes()) {
+		if (name !== undefined && name !== null) {
+			owners.set(name, SHELL_OWNER);
+		}
+	}
+
+	for (const module of modules) {
+		if (!module.routes) continue;
+
+		for (const name of declaredRouteNames(module.routes)) {
+			const owner = owners.get(name);
+			if (owner !== undefined) {
+				throw new Error(
+					`Duplicate route name "${String(name)}" declared by module "${module.id}" — already taken by ${owner}.`,
+				);
+			}
+			owners.set(name, `module "${module.id}"`);
+		}
+	}
+}

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-	"extends": "@n8n/typescript-config/tsconfig.frontend.json",
-	"compilerOptions": {
-		"rootDirs": [".", "../design-system/src", "../composables/src"],
-		"noEmit": true,
-		"moduleResolution": "bundler",
-		"types": [
-			"vite/client",
-			"vitest/globals",
-			"unplugin-icons/types/vue",
-			"../design-system/src/shims-modules.d.ts"
-		],
-		"paths": {
-			"@n8n/design-system*": ["../design-system/src*"],
-			"@n8n/composables*": ["../composables/src*"],
-			"@n8n/utils*": ["../../../@n8n/utils/src*"]
-		}
-	},
-	"include": ["src/**/*.ts", "vite.config.ts"]
-}