ue-assets-manifest

Maintain a ue-assets manifest

ue-assets is a Node CLI (npx ue-assets, Node ≥ 18) that installs/updates UE plugins and content from GitHub Releases. A project declares its dependencies in a JSON manifest (default plugins.json); the CLI downloads each release ZIP, extracts it into the install dir, and records the installed version in an auto-derived *-lock.json (plugins.json → plugins-lock.json) so unchanged entries are skipped on the next run.

Reference implementation: the ue-assets CLI — npm package ue-assets, source github.com/echoulen/ue-assets-cli (inspect its lib/ if behaviour is unclear).

Manifest format

{
  "dir": "../../Plugins",
  "plugins": {
    "MyPlugin": {
      "repo": "owner/repo",
      "version": "v1.2.3",
      "asset": "MyPlugin-{version}.zip"
    }
  }
}

• Root key is plugins or content — it must match the --config you run (plugins.json → plugins, content.json → content).
• dir (optional): default install dir; CLI --dir overrides it; falls back to Plugins/. Per-entry "dest" overrides dir for that one asset.
• repo: owner/repo hosting the GitHub Releases.
• version: an existing release tag (e.g. v1.2.3).
• asset: the release asset filename; {version} is substituted at runtime — prefer it over hardcoding the tag so update keeps asset valid.

Maintaining the manifest

• Add a dependency: add one entry under plugins (or content). Pick repo; set version to a real release tag; set asset to that release's ZIP filename using the {version} placeholder. Then apply (install below).
• Bump a dependency: either hand-edit version, or run npx ue-assets update <Name> to bump it to the latest release tag in-place (the CLI verifies the asset exists and rolls the manifest back on failure).
• Remove a dependency: delete its entry. The CLI does not delete installed files — remove the extracted folder manually if needed.
• Never hand-edit *-lock.json. It is CLI-managed. Commit the manifest (plugins.json); follow the project's existing policy on committing the lock.

Applying with the CLI

Requires GITHUB_TOKEN (scope contents:read) in .env at the project root or in the environment.

npx ue-assets install                 # all of plugins.json (skips locked versions)
npx ue-assets install --config content # use content.json instead
npx ue-assets install --dir ./Plugins  # override the manifest "dir"
npx ue-assets install --clean          # force remove + reinstall
npx ue-assets update                   # bump every entry to latest release
npx ue-assets update MyPlugin          # bump only one

--config auto-appends .json when given a name without an extension.

Common mistakes

Symptom	Fix
install does nothing	Version already in *-lock.json; use --clean or update.
401 / not found from GitHub	Missing/insufficient GITHUB_TOKEN (needs contents:read), or wrong repo.
Asset not found in release	asset filename mismatch — check the real release assets; keep the {version} placeholder.
Files land in the wrong place	Set manifest dir, per-entry dest, or pass --dir.
Root-key error	--config content requires the JSON root key to be content, not plugins.

Scope / not yet

The multi-sub-package module field + per-release manifest.json (R2/S3 large blobs) is a draft spec in ue-assets-cli/docs/superpowers/, not shipped. Until it lands, use only repo / version / asset per entry — do not add a module field.