Developers Package and install

Package and install

A Terminay extension is one ordinary npm package. Its manifest belongs in the terminay object of package.json, and it ships as an npm pack-compatible gzip tarball.

Prepare the package

Publish compiled ESM, not TypeScript source. Keep the manifest, entrypoint, permissions, contribution(s), compatible API range, and Node/Terminay engine ranges together in package.json.

JSON

{
  "name": "@acme/terminay-widget",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],
  "peerDependencies": { "@terminay/extension-api": "^1.2.0" },
  "devDependencies": { "@terminay/extension-api": "^1.2.0" },
  "terminay": {
    "manifestVersion": 1,
    "id": "com.acme.widget",
    "displayName": "Acme widget",
    "api": "^1.2.0",
    "engines": { "terminay": ">=1.0.0", "node": ">=20" },
    "entrypoint": "dist/index.js",
    "permissions": [],
    "contributes": { "projectEnvironments": [] }
  }
}

Replace the empty contribution array with an agentProviders or projectEnvironments contribution before packing. At least one supported contribution is required.

Build and pack

Shell

npm run build
npm pack --dry-run
npm pack
# @acme-terminay-widget-1.0.0.tgz

Check the dry run first: the archive must contain the manifest and its relative ESM entrypoint. The v1 upload limit is 12 MiB compressed.

Install the tarball

Open Settings → Extensions for the server that should run the extension.
Choose Install package file… and select the generated .tgz.
Review the exact package/version, digest, permissions, dependencies, and trusted-code warning.
Confirm the preview. Terminay validates, activates, and records the exact artifact.

The client uploads bytes to the selected server; it never gives that server a local path. Uploaded preview data expires after ten minutes. The installed package is labelled Uploaded package · Unverified unless it matches a release-pinned official artifact.

What the installer accepts

Accepted	Rejected in v1
Public npmjs dependencies with integrity, or the uploaded root tarball	Git, HTTP, alias, local file/directory, alternative-registry, and shell-like dependency specifications
Production JavaScript dependencies	Lifecycle/install scripts, native `.node` modules, `binding.gyp`, binary links, symlinks, and escaping paths

Terminay installs into an immutable slot with scripts disabled, probes the extension in a fresh host, and only then changes the active version. A failed install leaves the previous active version alone.