Release assets
A community plugin installs only main.js, manifest.json and styles.css. A large optional data file, such as a dictionary, a model or a WASM payload a feature needs only when the user turns it on, does not belong in main.js, where every user pays for it at every startup. ensureReleaseAsset from @mnaoumov/obsidian-lib/release-asset fetches such a file from the plugin’s release when it is first needed, and works the same on desktop and mobile.
Keep code out of it: a worker or any other executable code ships readable inside the bundle, where the community review can read it. This helper is for data.
ensureReleaseAsset
Section titled “ensureReleaseAsset”import { ensureReleaseAsset, getGitHubReleaseAssetUrl} from '@mnaoumov/obsidian-lib/release-asset';
const asset = await ensureReleaseAsset({ abortSignal, app: plugin.app, cacheFolderPath: `${plugin.manifest.dir ?? ''}/assets`, fileName: 'dictionary.bin', sha256: '3a6eb0790f39ac87c94f3856b2dd2c5d110e6811602261a9a923d3bb23adc8b7', sizeInBytes: 12_582_912, url: getGitHubReleaseAssetUrl({ fileName: 'dictionary.bin', repository: 'owner/my-plugin', tag: plugin.manifest.version })});
if (asset) { const bytes = await plugin.app.vault.adapter.readBinary(asset.path); console.log(asset.resourceUrl, bytes.byteLength);}It resolves with the path of the cached file, its resourceUrl from the adapter’s getResourcePath, and wasCached, which says whether anything was downloaded. It resolves with null when the user declines.
Put the cache under the plugin’s own folder, plugin.manifest.dir. That folder is not synced, so every device downloads the asset once, and uninstalling the plugin removes it.
Inside a plugin built on PluginBase, pass this.abortSignalComponent.abortSignal, so unloading the plugin stops the operation.
What it guarantees
Section titled “What it guarantees”- The cache is checked first, by content. A cached file is hashed on every call. A match is returned without asking anything or touching the network. A mismatch, from a truncated write or a hand edit, is removed and downloaded again, so a corrupt cache repairs itself.
- The user is asked only when a download is needed. By default a confirmation modal names the file, its size when
sizeInBytesis given, and the host it comes from. PassshouldDownloadto ask another way, or() => Promise.resolve(true)when the user has already agreed through a setting. Declining writes nothing and resolves withnull, so the next call asks again. - Nothing unverified is written or exposed. The downloaded bytes are hashed before they are written. A mismatch throws a
ReleaseAssetChecksumErrorcarryingexpectedSha256,actualSha256andurl. - No partial file is left under the cached name. The bytes are written to
<fileName>.downloadand then renamed into place. A failed write removes the temporary file and rethrows. - An abort stops it at every step. An aborted signal rejects with the signal’s reason before the cache is read, after the user answers and after the download, so nothing is written once the plugin has unloaded.
requestUrlcannot be cancelled, so a download in progress runs on in the background and its bytes are dropped. - Concurrent calls share one operation. Two features asking for the same file at the same time see one question and one download.
- A download failure is not swallowed. A network error, a timeout (
timeoutInMilliseconds) or an HTTP error status rejects with the error fromrequestUrlEx. See HTTP requests.
Getting the checksum
Section titled “Getting the checksum”Compute the SHA-256 of the file you attach to the release, and keep it in the plugin’s source beside the file name, so a release can only serve the bytes that version was built with. computeSha256 gives the same lowercase hexadecimal form in the renderer, and sha256sum or Get-FileHash gives it on the command line.