feat(extensions): lazy per-command loading via a nativescript.commands map

edusperoni · edusperoni · commit ba484815bfb7 · 2026-07-29T22:44:28.000-03:00
An extension whose package.json declares nativescript.commands as a map of
command name to module path is no longer require()d at startup. Each entry is
registered with injector.requireCommand against the module's absolute path, so
a command's implementation loads only when that command is first resolved, and
the CLI stops paying every installed extension's load cost on every
invocation.

Entries are validated: a command name or module path that is not a non-empty
string is warned about and skipped, and a name already claimed by another
extension is reported as a warning naming both extensions rather than
propagating the injector's "require'd twice" failure.

The legacy array shape (and a missing commands key) keeps today's behavior
verbatim - eager require of the extension main plus the
extensions.require-time-registration deprecation report. Both shapes now feed
IExtensionData.commands and the npm install suggestion for unknown commands.
diff --git a/extensions.md b/extensions.md
@@ -0,0 +1,179 @@
+Writing a CLI Extension
+=======================
+
+An extension adds new commands to the NativeScript CLI. Extensions are ordinary
+npm packages: they are published to npm, installed per user rather than per
+project, and are available from every project on the machine.
+
+```bash
+ns extension install <package-name>
+ns extension uninstall <package-name>
+```
+
+Installed extensions live in the CLI profile directory, under
+`extensions/node_modules/<package-name>`, and every CLI invocation consults each
+of them. That makes the manifest below the most important file in an extension:
+it is what the CLI reads on startup, and it decides whether your code is loaded
+eagerly or only when one of your commands is actually executed.
+
+## Making a package discoverable
+
+Add the `nativescript:extension` keyword to `package.json`. The CLI searches npm
+for that keyword when it needs to suggest an extension for an unknown command
+(see [Suggesting an extension](#suggesting-an-extension-for-an-unknown-command)).
+
+```json
+{
+	"name": "nativescript-hello",
+	"version": "1.0.0",
+	"keywords": ["nativescript:extension"]
+}
+```
+
+## Declaring commands
+
+Commands are declared in the `commands` key of the `nativescript` key of the
+extension's `package.json`. Two shapes are accepted.
+
+### A map of command name to module (recommended)
+
+```json
+{
+	"nativescript": {
+		"commands": {
+			"hello|world": "./dist/commands/hello-world.js",
+			"hello|*default": "./dist/commands/hello.js"
+		}
+	}
+}
+```
+
+Each key is a command name; each value is a path to the module implementing it,
+resolved relative to the extension's root directory.
+
+Declaring commands this way is strongly preferred:
+
+* **Per-command lazy loading.** Nothing in the extension is loaded when the CLI
+  starts. A command's module is required the first time that command is
+  resolved, so `ns build android` never pays the cost of loading an unrelated
+  extension. With a large or dependency-heavy extension installed, that is the
+  difference between a noticeable startup delay on every command and none.
+* **Early, named conflict detection.** Two extensions claiming the same command
+  name is reported as a warning that names both extensions and the contested
+  command, and the extension that claimed it first keeps working. Under the
+  legacy shape the same collision surfaces as an opaque
+  `module '...' require'd twice.` failure from whichever extension happened to
+  load second.
+* **The CLI knows what you contribute without running you.** The declared
+  command names are what the install suggestion for an unknown command matches
+  against, and they are available to the CLI as metadata about the installed
+  extension.
+
+Malformed entries are skipped rather than fatal: an entry whose command name or
+module path is not a non-empty string is reported as a warning naming the
+extension and the offending entry, and the extension's remaining commands are
+still registered.
+
+### An array of command names (legacy)
+
+```json
+{
+	"nativescript": {
+		"commands": ["hello|world", "hello|*default"]
+	}
+}
+```
+
+The array is a discovery aid only — it lists the names the CLI may suggest your
+extension for, but it says nothing about where the implementations live. An
+extension declaring commands this way (or declaring no commands at all) is
+loaded the old way: the CLI `require()`s the package's main entry on **every**
+invocation and expects the module's top-level code to register everything.
+
+```js
+// index.js of a legacy extension
+const path = require("path");
+
+global.$injector.requireCommand(
+	"hello|world",
+	path.join(__dirname, "commands", "hello-world"),
+);
+```
+
+This path remains supported, but it is tracked for eventual deprecation. Run any
+command with `--log trace` to see which installed extensions still rely on it,
+or set `NS_DEPRECATIONS=warn` to have those reports printed as warnings.
+
+## Writing a command module
+
+A command module must register itself when it is loaded, by calling
+`$injector.registerCommand` at the top level with the same name it is declared
+under in the manifest. The CLI resolves the command through the injector right
+after loading the module, so registration has to happen as a side effect of the
+`require`.
+
+```js
+// dist/commands/hello-world.js
+class HelloWorldCommand {
+	constructor($logger) {
+		this.$logger = $logger;
+		this.allowedParameters = [];
+	}
+
+	async execute(args) {
+		this.$logger.info(`Hello, ${args[0] || "world"}!`);
+	}
+}
+
+global.$injector.registerCommand("hello|world", HelloWorldCommand);
+```
+
+Constructor parameters are injected by name: a parameter called `$logger`
+receives the CLI's logger, `$fs` its file system service, and so on. A command
+class must expose `allowedParameters` and an `execute(args)` method.
+
+## Command names
+
+Command names use `|` to express hierarchy, so `"hello|world"` is invoked as
+`ns hello world`. Prefixing the last segment with `*` marks a default
+subcommand: `"hello|*default"` runs both for `ns hello default` and for a bare
+`ns hello`.
+
+When an extension contributes several commands under the same parent, declare
+the default command before its siblings — the CLI creates the parent dispatcher
+from the first entry it sees, and a default command registered after that parent
+already exists is rejected.
+
+## Suggesting an extension for an unknown command
+
+When a user types a command the CLI does not know, it searches npm for packages
+carrying the `nativescript:extension` keyword, reads the `nativescript.commands`
+key of each candidate's published `package.json`, and matches it against the
+words the user typed — longest match first, so `ns valid command with args`
+matches a declared `valid|command|with` before `valid|command`. A declared
+default command also matches its short form: an extension declaring
+`hello|*default` is suggested for a bare `ns hello`.
+
+Both manifest shapes participate in this matching. If a match is found, the CLI
+tells the user which extension provides the command and how to install it:
+
+```
+The command hello world is registered in extension nativescript-hello.
+You can install it by executing 'ns extension install nativescript-hello'
+```
+
+## Documentation
+
+Point the `docs` key of the `nativescript` key at a directory of `.md` files to
+have the CLI's help system pick up the help for your commands.
+
+```json
+{
+	"nativescript": {
+		"docs": "./docs",
+		"commands": {
+			"hello|world": "./dist/commands/hello-world.js"
+		}
+	}
+}
+```
diff --git a/lib/common/definitions/extensibility.d.ts b/lib/common/definitions/extensibility.d.ts
@@ -30,6 +30,13 @@ interface IExtensionData extends IExtensionName {
 	 * Full path to the directory of the installed extension.
 	 */
 	pathToExtension: string;
+
+	/**
+	 * Names of the commands the extension contributes, as declared in the commands key of the nativescript key of its package.json.
+	 * The key may be a map of command name to the module implementing it, in which case these are its keys, or the legacy array of command names, in which case these are its entries.
+	 * The property is not set when the extension declares no commands.
+	 */
+	commands?: string[];
 }
 
 /**
diff --git a/lib/services/extensibility-service.ts b/lib/services/extensibility-service.ts
@@ -19,9 +19,40 @@ import {
 } from "../common/definitions/extensibility";
 import { injector } from "../common/yok";
 
+function isNonEmptyString(value: any): boolean {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isCommandsMap(commands: any): boolean {
+	return !!commands && typeof commands === "object" && !Array.isArray(commands);
+}
+
+/**
+ * Reads the names of the commands an extension contributes out of either shape
+ * of `nativescript.commands` - the legacy array of names, or the map of name to
+ * module path.
+ */
+function getDeclaredCommandNames(
+	commands: any,
+	opts?: { copy: boolean },
+): string[] {
+	if (Array.isArray(commands)) {
+		return opts && opts.copy ? commands.slice() : commands;
+	}
+
+	if (isCommandsMap(commands)) {
+		return _.keys(commands);
+	}
+
+	return null;
+}
+
 export class ExtensibilityService implements IExtensibilityService {
 	private customPathToExtensions: string = null;
 
+	/** Command name -> name of the extension whose manifest claimed it first. */
+	private manifestCommandOwners: IStringDictionary = {};
+
 	private get pathToPackageJson(): string {
 		return path.join(this.pathToExtensions, constants.PACKAGE_JSON_FILE_NAME);
 	}
@@ -132,25 +163,47 @@ export class ExtensibilityService implements IExtensibilityService {
 			packageJsonData.nativescript &&
 			packageJsonData.nativescript.docs &&
 			path.join(pathToExtension, packageJsonData.nativescript.docs);
-		return {
+		const result: IExtensionData = {
 			extensionName: packageJsonData.name,
 			version: packageJsonData.version,
 			docs,
 			pathToExtension,
 		};
+
+		const commands = getDeclaredCommandNames(
+			packageJsonData &&
+				packageJsonData.nativescript &&
+				packageJsonData.nativescript.commands,
+		);
+		if (commands) {
+			result.commands = commands;
+		}
+
+		return result;
 	}
 
 	public async loadExtension(extensionName: string): Promise<IExtensionData> {
 		try {
 			await this.assertExtensionIsInstalled(extensionName);
 
 			const pathToExtension = this.getPathToExtension(extensionName);
-			reportDeprecation({
-				api: "extensions.require-time-registration",
-				detail: extensionName,
-				logger: this.$logger,
-			});
-			this.$requireService.require(pathToExtension);
+			const commandsMap = this.getDeclaredCommandsMap(extensionName);
+
+			if (commandsMap) {
+				this.registerDeclaredCommands(
+					extensionName,
+					pathToExtension,
+					commandsMap,
+				);
+			} else {
+				reportDeprecation({
+					api: "extensions.require-time-registration",
+					detail: extensionName,
+					logger: this.$logger,
+				});
+				this.$requireService.require(pathToExtension);
+			}
+
 			return this.getInstalledExtensionData(extensionName);
 		} catch (error) {
 			this.$logger.warn(
@@ -200,10 +253,13 @@ export class ExtensibilityService implements IExtensibilityService {
 					await this.$packageManager.getRegistryPackageData(extensionName);
 				const latestPackageData =
 					registryData.versions[registryData["dist-tags"].latest];
-				const commands: string[] =
+				const commands = getDeclaredCommandNames(
 					latestPackageData &&
-					latestPackageData.nativescript &&
-					latestPackageData.nativescript.commands;
+						latestPackageData.nativescript &&
+						latestPackageData.nativescript.commands,
+					// The |* synthesis below pushes into this array.
+					{ copy: true },
+				);
 				if (commands && commands.length) {
 					// For each default command we need to add its short syntax in the array of commands.
 					// For example in case there's a default command called devices list, the commands array will contain devices|*list.
@@ -249,6 +305,74 @@ export class ExtensibilityService implements IExtensibilityService {
 		return null;
 	}
 
+	/**
+	 * Returns the `nativescript.commands` value of an extension only when it is a
+	 * map of command name to module path. Any other shape (the legacy array of
+	 * command names, a missing key, an unreadable package.json) yields null and
+	 * keeps the extension on the eager require path.
+	 */
+	private getDeclaredCommandsMap(extensionName: string): IStringDictionary {
+		let commands: any;
+
+		try {
+			const packageJsonData = this.getExtensionPackageJsonData(extensionName);
+			commands =
+				packageJsonData &&
+				packageJsonData.nativescript &&
+				packageJsonData.nativescript.commands;
+		} catch (err) {
+			this.$logger.trace(
+				`Unable to read the package.json of extension ${extensionName}. Error is: ${err}`,
+			);
+			return null;
+		}
+
+		return isCommandsMap(commands) ? commands : null;
+	}
+
+	/**
+	 * Registers each declared command as a deferred require of its own module, so
+	 * nothing from the extension is loaded until one of its commands is executed.
+	 * Each module is expected to register itself on load, by calling
+	 * `$injector.registerCommand(<name>, <class>)` at the top level.
+	 */
+	private registerDeclaredCommands(
+		extensionName: string,
+		pathToExtension: string,
+		commands: IStringDictionary,
+	): void {
+		for (const commandName of _.keys(commands)) {
+			const modulePath = commands[commandName];
+
+			if (!isNonEmptyString(commandName) || !isNonEmptyString(modulePath)) {
+				this.$logger.warn(
+					`Extension ${extensionName} declares an invalid command in its nativescript.commands: '${commandName}': ${JSON.stringify(
+						modulePath,
+					)}. Both the command name and the path to its module must be non-empty strings. Skipping this command.`,
+				);
+				continue;
+			}
+
+			try {
+				injector.requireCommand(
+					commandName,
+					path.join(pathToExtension, modulePath),
+				);
+			} catch (err) {
+				const owner = this.manifestCommandOwners[commandName];
+				const ownerInfo = owner
+					? ` It is already registered by extension ${owner}.`
+					: "";
+				this.$logger.warn(
+					`Extension ${extensionName} is unable to register command ${commandName}.${ownerInfo} Error: ${err.message}`,
+				);
+				continue;
+			}
+
+			this.manifestCommandOwners[commandName] = extensionName;
+		}
+	}
+
 	private getPathToExtension(extensionName: string): string {
 		return path.join(
 			this.pathToExtensions,
diff --git a/test/extension-manifests.ts b/test/extension-manifests.ts
