Packaging and recovery

The M1 alpha provides pnpm package: build, ZIP readback, SHA-256 and a validation report. See the generator guide. npm package versions are pinned by the generator. Extract the ZIP before importing.

Build a release

In a generated project, run:

pnpm check
pnpm package

package builds again, validates the output folder, creates a ZIP, extracts it for verification and compares its files. It publishes nothing to npm, GitHub or a plugin store. Increase version in plugin.json before another release; package.json does not determine artifact names.

File	Contents
<id>-<version>.zip	Built plugin with plugin.json at the archive root
<id>-<version>.sha256	ZIP SHA-256 and filename
<id>-<version>.validation.json	CLI/SDK versions, ZIP SHA-256, file sizes and hashes, desktopTested: false

Files go into artifacts/. Existing artifact names cause PLUGIN_RELEASE_EXISTS; releases are never overwritten. ZIP hashes let recipients compare downloads with the author’s file. This is separate from the content revision Lomi approves when enabling code. Neither hash alone establishes publisher identity.

Build output

package/ contains browser ES2022 ESM, the manifest and explicit assets. Builds share React and SDK instances with the host, bundle other compatible libraries and validate relative imports. Vite aliases and private application sources are unavailable.

Successful builds replace previous output; failures preserve the last good folder. Source maps contain paths without embedded source text, and declaration files are not generated. See Tools for CLI configuration and the manual SDK example for every buildPlugin() option.

Distribute the folder

Share the contents of package/. If you use an archive for transport, the recipient must extract it and select the resulting folder in Import plugin. Installation does not run pnpm install, build commands or lifecycle scripts.

For theme contributions, include the theme directory in assets and point contributes.themes[].path at that directory. The theme becomes available on import without running code. Plugin-owned themes are read-only; users can duplicate them before editing.

Package limits

Item	Limit
Installed packages	128
One package	64 MiB
Files and directories	2048 entries
Directory nesting	16 levels
One file	20 MiB
Manifest metadata	256 KiB

The native importer rejects invalid paths, symlinks and special files. Do not distribute node_modules, caches or the source checkout as the installed package.

Replace a revision

1. Disable the installed plugin and resolve any unsaved views.
2. Build and import the replacement folder with the same plugin ID.
3. Review and enable the new revision.
4. Restart the application when Restart required appears.

Trust applies to the complete package content hash. Reimporting installs a disabled, untrusted revision. Updating only the semantic version does not bypass review. Once evaluated, JavaScript modules cannot be unloaded from the engine; a changed revision needs a restart. The same revision can be cooperatively deactivated and activated again.

Before uninstalling a package that supplies selected themes, switch its selected color and icon themes to built-in alternatives. The native removal checks include all selected theme kinds.

Roll back an update

Keep the previous extracted package. Disable the new revision, import the previous folder with the same ID, review and approve it. Restart if another revision’s code has already run. Reverting the release number does not automatically restore state compatibility: old code must understand the saved stateVersion and placement.

What to give recipients

Alongside the ZIP, provide short installation instructions, plugin version, supported and actually tested Lomi versions and platforms, licensing and release notes. Explain network requirements and data persistence. Recipients need the built package, not Node, Rust or an npm account. Complete a desktop qualification before release.

Diagnose a failure

Symptom	What to check
Undeclared contribution	The registered ID must exist in plugin.json.
Plugin view unavailable	Enable the owner and check the saved stateVersion and placement.
Restart required	Restart after resolving unsaved work.
Lomi host is missing	Run the built package inside the desktop host, not as a standalone webpage.
Import reports a missing file	Inspect the generated package/, the manifest paths and assets.
No statusbar control	Check activation: lazy fills need another activation trigger.
Command missing or unavailable	Check enablement, context.workspace, viewTypes and the command declaration.
Shortcut does not work	Check Settings > Keybinds, conflicts, key codes and textInput.
Code change is not visible	Verify build success, package/ reimport, trust and restart.
State returns to defaults	Check setState(), the view ID and the current workspace.
Plugin activation was disposed.	Do not reuse an old context after await; check signal.aborted.
Cannot uninstall a theme package	Switch away from all active themes supplied by that package.

Settings > Plugins > Details shows the package ID, source, trust and runtime status. Render failures offer Retry view; failed activation can offer Retry activation. Handle errors from the plugin’s own asynchronous operations as well.

Safe startup

Close the application, then start its executable with --safe-mode. For a development checkout:

pnpm tauri dev -- -- --safe-mode

For a Linux installation whose executable is on PATH:

lomi --safe-mode

On macOS, an application installed in Applications can be started directly:

/Applications/Lomi.app/Contents/MacOS/lomi --safe-mode

On Windows, pass --safe-mode to the installed lomi.exe using its actual location.

Safe startup skips third-party code and custom themes before evaluation. Disable the faulty plugin in Settings, then close and reopen normally. --disable-plugins also selects the baseline theme. LOMI_SAFE_MODE activates safe startup whenever the environment variable is present, even if its value is 0.

If the catalogue plugins/installed.json is corrupt, close the app and rename it to plugins/installed.backup.json in the application data directory. Start in safe mode and reimport the desired packages. Keep package folders and the session file. A plugin that blocks the main thread may require terminating the process before safe startup is possible.

Source: build helper, package storage and safe startup.