@n8n/frontend-module-sdk 0.9.3 → 0.10.0

package/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/README.md

@@ -2,19 +2,54 @@
 
 The frontend module contract and registries for n8n editor modules.
 
-This package owns the `FrontendModuleDescription` descriptor type plus the modal
-and resource registries that features register against. The editor shell keeps
-the wiring (`moduleInitializer`) that drives the two-phase lifecycle; this
-package only defines the contract and the registry state.
+This package owns the `FrontendModuleDescription` descriptor type, the
+`defineFrontendModule()` helper that declares one, plus the modal and resource
+registries that features register against. The editor shell keeps the wiring
+(`moduleInitializer`) that drives the two-phase lifecycle; this package only
+defines the contract and the registry state.
 
 It is a source-only package (no build step): consumers resolve it from `src`
 via the editor-ui Vite alias and `tsconfig` paths, and `src/index.ts` is the
 only public entry point.
 
 ```ts
-import { modalRegistry, registerResource, type FrontendModuleDescription } from '@n8n/frontend-module-sdk';
+import { defineFrontendModule, modalRegistry, registerResource } from '@n8n/frontend-module-sdk';
 ```
 
+## Declaring a module
+
+`defineFrontendModule()` is the canonical descriptor form. Use it for every
+module, in the shell and in a module package alike.
+
+```ts
+export const MyFeatureModule = defineFrontendModule({
+	// Must match the backend module id: both gate off `/rest/module-settings`.
+	id: 'my-feature',
+	name: 'My Feature',
+	description: 'What this module does',
+	icon: 'box',
+});
+```
+
+The helper is the identity function at runtime. It returns the object that it
+gets. It does not wrap, clone, or freeze it, so a getter-backed field such as
+`available` stays lazy.
+
+Two reasons to prefer it over a `: FrontendModuleDescription` annotation:
+
+- **One seam.** The SDK gets one function to attach descriptor validation or a
+  dev-mode check to, instead of declaration sites it cannot see.
+- **Inference.** `const T` keeps the literal type of each field, so
+  `MyFeatureModule.id` is `'my-feature'` and not `string`.
+
+Do not use both. An annotation on top of the helper widens the types again.
+
+Keep the descriptor file import-light: types and the SDK at module scope only.
+Load a view with `async () => await import('./views/X.vue')`, and read a store
+inside a route guard, a push handler, or `setup`. The shell manifest imports
+every descriptor eagerly, so a top-level store import pulls the module into the
+boot chunk even when the module is off.
+
 ## Push handlers
 
 A module owns a push message type when it declares it in `pushHandlers`. The

package/package.json

@@ -1,24 +1,24 @@
 {
   "type": "module",
   "name": "@n8n/frontend-module-sdk",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "main": "src/index.ts",
   "import": "src/index.ts",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@n8n/api-types": "1.39.3",
-    "@n8n/design-system": "2.38.3",
-    "@n8n/utils": "1.47.0",
-    "n8n-workflow": "2.39.1",
+    "@n8n/api-types": "1.40.0",
+    "@n8n/design-system": "2.39.0",
+    "@n8n/utils": "1.48.0",
+    "n8n-workflow": "2.40.0",
     "vue": "^3.5.13",
     "vue-router": "^4.5.0"
   },
   "devDependencies": {
     "@n8n/eslint-config": "0.0.1",
-    "@n8n/typescript-config": "1.11.0",
-    "@n8n/vitest-config": "1.21.0",
+    "@n8n/typescript-config": "1.12.0",
+    "@n8n/vitest-config": "1.22.0",
     "typescript": "6.0.2",
     "unplugin-icons": "^23.0.1",
     "vite": "^8.0.2",

package/src/defineFrontendModule.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, expectTypeOf } from 'vitest';
+
+import { defineFrontendModule } from './defineFrontendModule';
+import type { FrontendModuleDescription } from './types/descriptor';
+
+describe('defineFrontendModule', () => {
+	it('should return the same object it was given', () => {
+		const descriptor = {
+			id: 'identity',
+			name: 'Identity',
+			description: 'A descriptor passed straight through',
+			icon: 'box',
+		};
+
+		expect(defineFrontendModule(descriptor)).toBe(descriptor);
+	});
+
+	it('should not freeze, seal, or clone the descriptor', () => {
+		const module: FrontendModuleDescription = defineFrontendModule({
+			id: 'mutable',
+			name: 'Mutable',
+			description: 'A descriptor that stays writable',
+			icon: 'box',
+			resources: [{ key: 'mutable', displayName: 'Mutable' }],
+		});
+
+		expect(Object.isFrozen(module)).toBe(false);
+		expect(Object.isSealed(module)).toBe(false);
+		expect(Object.isExtensible(module)).toBe(true);
+
+		// The shell reads a descriptor through the contract type, and registration
+		// order lets a host append. Nothing the helper does may prevent that.
+		module.resources?.push({ key: 'added', displayName: 'Added' });
+		expect(module.resources).toHaveLength(2);
+	});
+
+	it('should keep a getter lazy instead of reading it', () => {
+		let reads = 0;
+		const module = defineFrontendModule({
+			id: 'lazy',
+			name: 'Lazy',
+			description: 'A descriptor with a getter-backed field',
+			icon: 'box',
+			get settingsPages() {
+				reads += 1;
+				return [];
+			},
+		});
+
+		expect(reads).toBe(0);
+		expect(module.settingsPages).toHaveLength(0);
+		expect(reads).toBe(1);
+	});
+
+	it('should keep the literal type of each field', () => {
+		const module = defineFrontendModule({
+			id: 'literal',
+			name: 'Literal',
+			description: 'A descriptor whose literal types survive',
+			icon: 'box',
+		});
+
+		expectTypeOf(module.id).toEqualTypeOf<'literal'>();
+		expectTypeOf(module.name).toEqualTypeOf<'Literal'>();
+		expectTypeOf(module.icon).toEqualTypeOf<'box'>();
+	});
+
+	it('should narrow optional fields a descriptor declares', () => {
+		const module = defineFrontendModule({
+			id: 'narrow',
+			name: 'Narrow',
+			description: 'A descriptor declaring one optional surface',
+			icon: 'box',
+			commands: [{ id: 'narrow.open', title: 'Open Narrow' }],
+		});
+
+		// An annotated descriptor widens this to `CommandBarEntry[] | undefined`.
+		expectTypeOf(module.commands).not.toBeUndefined();
+		expectTypeOf(module).toExtend<FrontendModuleDescription>();
+	});
+
+	it('should type-check a descriptor against the contract', () => {
+		// @ts-expect-error `id` is required.
+		defineFrontendModule({ name: 'No id', description: '', icon: 'box' });
+
+		// @ts-expect-error `icon` must be a string.
+		defineFrontendModule({ id: 'typed', name: 'Typed', description: '', icon: 42 });
+
+		// @ts-expect-error `routes` must hold route records.
+		defineFrontendModule({ id: 'typed', name: 'Typed', description: '', icon: 'box', routes: [1] });
+	});
+
+	it('should keep array element types narrow under `const` inference', () => {
+		const module = defineFrontendModule({
+			id: 'narrow-elements',
+			name: 'Narrow elements',
+			description: 'A descriptor whose array elements keep their literal types',
+			icon: 'box',
+			resources: [{ key: 'thing', displayName: 'Thing' }],
+		});
+
+		expectTypeOf(module.resources[0].key).toEqualTypeOf<'thing'>();
+		expect(module.resources[0].key).toBe('thing');
+	});
+
+	it('should type a route guard from the contract', () => {
+		const module = defineFrontendModule({
+			id: 'guarded',
+			name: 'Guarded',
+			description: 'A descriptor whose guard parameter is typed by the contract',
+			icon: 'box',
+			routes: [
+				{
+					path: '/guarded',
+					component: async () => await Promise.resolve({}),
+					beforeEnter: (to) => {
+						expectTypeOf(to.params).not.toBeAny();
+						return true;
+					},
+				},
+			],
+		});
+
+		expect(module.routes).toHaveLength(1);
+	});
+});

package/src/defineFrontendModule.ts

@@ -0,0 +1,29 @@
+import type { FrontendModuleDescription } from './types/descriptor';
+
+/**
+ * Declares a frontend module descriptor.
+ *
+ * Identity at runtime: it returns the object it was given. It does not wrap,
+ * clone, or freeze it, so a descriptor declared through it behaves exactly as a
+ * descriptor declared with a type annotation.
+ *
+ * What it adds is a seam and inference. The seam gives the SDK one place to
+ * attach validation or a dev-mode check later, instead of ten declaration sites
+ * it cannot see. The inference keeps each field's literal type — `MyModule.id`
+ * reads as `'my-feature'`, not `string` — which an annotation widens away.
+ *
+ * Use it for every descriptor. An annotated descriptor still satisfies the type,
+ * but it is not the canonical form.
+ *
+ * ```ts
+ * export const MyFeatureModule = defineFrontendModule({
+ *   id: 'my-feature',
+ *   name: 'My Feature',
+ *   description: 'What this module does',
+ *   icon: 'box',
+ * });
+ * ```
+ */
+export function defineFrontendModule<const T extends FrontendModuleDescription>(module: T): T {
+	return module;
+}

package/src/index.ts

@@ -1,9 +1,11 @@
 export type * from './types';
 
+export { defineFrontendModule } from './defineFrontendModule';
 export { assertUniqueRouteNames } from './routeNames';
 
 export * as modalRegistry from './registries/modalRegistry';
 export * from './registries/resourceRegistry';
 export * as pushHandlerRegistry from './registries/pushHandlerRegistry';
 export * as commandRegistry from './registries/commandRegistry';
+export * as componentRegistry from './registries/componentRegistry';
 export * as parameterInputRegistry from './registries/parameterInputRegistry';

package/src/registries/componentRegistry.test.ts

@@ -0,0 +1,73 @@
+import { computed, defineComponent } from 'vue';
+
+import * as componentRegistry from './componentRegistry';
+
+const First = defineComponent({ template: '<div>first</div>' });
+const Second = defineComponent({ template: '<div>second</div>' });
+
+describe('componentRegistry', () => {
+	beforeEach(() => {
+		componentRegistry.clear();
+	});
+
+	it('resolves a registered slot', () => {
+		componentRegistry.register('project-filter', First);
+
+		expect(componentRegistry.get('project-filter')).toBe(First);
+		expect(componentRegistry.has('project-filter')).toBe(true);
+	});
+
+	it('resolves an unregistered slot to undefined', () => {
+		expect(componentRegistry.get('project-filter')).toBeUndefined();
+		expect(componentRegistry.has('project-filter')).toBe(false);
+	});
+
+	it('treats re-registering the same component as a no-op', () => {
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+		componentRegistry.register('project-filter', First);
+		componentRegistry.register('project-filter', First);
+
+		expect(componentRegistry.get('project-filter')).toBe(First);
+		expect(warn).not.toHaveBeenCalled();
+	});
+
+	it('keeps the first component and warns when a second claims the slot', () => {
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+		componentRegistry.register('project-filter', First);
+		componentRegistry.register('project-filter', Second);
+
+		expect(componentRegistry.get('project-filter')).toBe(First);
+		expect(warn).toHaveBeenCalledWith(
+			'Component slot "project-filter" is already registered. Skipping.',
+		);
+	});
+
+	// The registry is `shallowReactive` so a module can resolve a slot with a plain
+	// `computed`. The shell registers slots lazily, after a module may already have
+	// read an empty slot — swapping in a plain `Map` would break that silently.
+	it('makes a computed reader see a later registration', () => {
+		const slot = computed(() => componentRegistry.get('project-filter'));
+		expect(slot.value).toBeUndefined();
+
+		componentRegistry.register('project-filter', First);
+
+		expect(slot.value).toBe(First);
+	});
+
+	it('makes a computed reader see an unregister', () => {
+		componentRegistry.register('project-filter', First);
+		const slot = computed(() => componentRegistry.get('project-filter'));
+		expect(slot.value).toBe(First);
+
+		componentRegistry.unregister('project-filter');
+
+		expect(slot.value).toBeUndefined();
+	});
+
+	it('frees the slot on unregister', () => {
+		componentRegistry.register('project-filter', First);
+		componentRegistry.unregister('project-filter');
+
+		expect(componentRegistry.get('project-filter')).toBeUndefined();
+	});
+});

package/src/registries/componentRegistry.ts

@@ -0,0 +1,42 @@
+import { shallowReactive, type Component } from 'vue';
+
+import type { ModuleComponentSlot } from '../types/component';
+
+/**
+ * Shell-hosted components, keyed by slot. The shell registers; modules read.
+ *
+ * Shallow-reactive so a module can resolve a slot with a plain `computed`, and
+ * shallow specifically so a component is never turned into a reactive object.
+ *
+ * A slot with nothing registered resolves to `undefined`, and the module renders
+ * nothing for it. That is the correct behavior in a module's own test run, where
+ * no shell exists — a test that needs the slot registers a stub.
+ */
+const components = shallowReactive(new Map<ModuleComponentSlot, Component>());
+
+export function register(slot: ModuleComponentSlot, component: Component): void {
+	const existing = components.get(slot);
+	if (existing && existing !== component) {
+		console.warn(`Component slot "${slot}" is already registered. Skipping.`);
+		return;
+	}
+
+	components.set(slot, component);
+}
+
+export function get(slot: ModuleComponentSlot): Component | undefined {
+	return components.get(slot);
+}
+
+export function has(slot: ModuleComponentSlot): boolean {
+	return components.has(slot);
+}
+
+export function unregister(slot: ModuleComponentSlot): void {
+	components.delete(slot);
+}
+
+/** Test isolation only. */
+export function clear(): void {
+	components.clear();
+}

package/src/types/component.ts

@@ -0,0 +1,22 @@
+/**
+ * UI a module renders but does not own.
+ *
+ * Each id names one shell-hosted component with a fixed contract. The union is
+ * closed on purpose: this is not a generic slot system, and adding an id is a
+ * reviewed change to the module contract, not a local decision.
+ *
+ * `project-filter` — a project picker. The project list, the permissions that
+ * decide between local and remote search, and the search itself all live in
+ * `features/collaboration/projects`, which sits above the module layer. A module
+ * that needs to filter by project renders this instead of importing any of it.
+ */
+export type ModuleComponentSlot = 'project-filter';
+
+/**
+ * The `v-model` value of the `project-filter` slot. `null` means "all projects".
+ *
+ * Deliberately narrow: `id` is all a consumer needs, and the host keeps the full
+ * project object. A consumer writes only `null` (to clear); every non-null value
+ * originates in the host.
+ */
+export type SlotProjectSelection = { id: string } | null;

package/src/types/index.ts

@@ -1,3 +1,4 @@
+export type * from './component';
 export type * from './descriptor';
 export type * from './modal';
 export type * from './parameterInput';