Installing

Installing means writing a package directory into a Host's package store so a runtime can later load it by name. The CLI command is mx install <source>, where <source> is one of three things:

1. A package name (resolved through the configured registry).
2. An absolute or relative path to a local package directory.
3. An absolute or relative path to a local tarball (.tar.gz / .tgz).

Source: packages/mx-cli/src/commands/install.ts:532-652.

Pages

• Install from registry — resolve a package name through the npm-compatible HTTP registry
• Install from Gitea — same code path as npm registry; this page documents the HiveCast Gitea registry's specifics and target-state Gitea-only conventions
• Install from local folder — install directly from a checkout
• Dependency resolution — runtime npm dependencies and the install lifecycle hooks
• Package store — where installed packages live on disk
• Uninstall — remove an installed package

What mx install does, in order

1. Resolve cwd, packagesDir, and nodeModulesRoot from --packages-dir or <MATRIX_HOME>/packages.
2. Inspect the source argument:
   • Existing directory → install from directory.
   • Existing file ending in .tar.gz/.tgz → extract, then install from the extracted directory.
   • Anything else → treat as a registry specifier.
3. For local sources, optionally invoke maybeBuildLocalTypescriptPackage if runtime.entry doesn't exist on disk yet — this transpiles src/ into a staging dir.
4. Copy the source into a staging dir, atomically rename into the target dir under node_modules/, and run lifecycle hooks (installRuntimeNpmDependencies, runInstallLifecycle).
5. If anything fails, restore the previous version from the backup directory written before the rename.

Atomicity comes from the staging-dir rename. The previous install is backed up first, so a failed install does not leave a half-written package store.

Force overwrite

mx install @open-matrix/chat --force

Without --force, installing over an existing package fails with Package already installed: <name>. With --force, the previous version is moved to a backup directory before the new one is moved into place; the backup is removed only after lifecycle hooks complete successfully.

See also

• Overview → Package lifecycle
• Publishing — the producing side of every install path
• Running — what to do once a package is installed
• Reference → CLI reference

Source: projects/matrix-3/packages/mx-cli/src/commands/install.ts contains the entire install flow; the lifecycle hooks live in the same file (runInstallLifecycle).