Skip to content
docs
GitHub
Plugins

Your first plugin

Create a panel, build its package and run it in Lomi step by step.

Build Workspace info: a panel showing the workspace name, project path and a preference saved in the session. You do not need application sources or a Rust compiler.

Before you start

Section titled “Before you start”

Use Node.js 22.14 or newer, pnpm 11.25.0 and a Lomi application supporting plugin API 1 and the Lomi runtime. Check your terminal:

Terminal window
node --version
pnpm --version

This guide describes SDK 1.1.0-alpha.1, CLI 0.1.0-alpha.2 and generator 0.1.0-alpha.3, the versions in the local rebrand source set. The npm generator command requires these versions to be published first. If the registry cannot find a version, follow the local archives instructions in Tools and diagnostics. An older package using a different runtime protocol is not a compatible substitute.

The SDK defines the plugin contract. The CLI checks and builds projects. The generator creates starter files; it does not install your plugin into Lomi.

1. Create a project

Section titled “1. Create a project”

Run these commands in a folder where you keep your projects:

Terminal window
pnpm create [email protected] my-plugin --id example.workspace-info --name "Workspace info" --template panel
cd my-plugin
pnpm install --ignore-scripts

my-plugin is the folder, example.workspace-info is the persistent plugin ID, and Workspace info is the display name. Use your own namespace for your project, such as anna.project-notes.

The destination must be new or empty. The generator does not overwrite files, install dependencies or initialize Git. Keep the resulting pnpm-lock.yaml; subsequent installations and CI should use pnpm install --frozen-lockfile --ignore-scripts.

2. Understand the files

Section titled “2. Understand the files”
my-plugin/
├── plugin.json              # Display name, version and contributions
├── src/index.tsx            # React view and activate function
├── view.css                 # Panel styles
├── lomi-plugin.config.mjs   # Build entry and copied assets
├── tsconfig.json            # TypeScript settings
├── package.json             # Author dependencies and commands
└── LICENSE                  # Template license

The project also contains JSON schema settings in .vscode/, a workflow in .github/, .gitignore and pnpm-workspace.yaml. Building creates package/; packaging creates artifacts/. Both are generated output.

package.json belongs to Node tooling. Lomi reads plugin.json. Change the application’s display name, ID and plugin version in that file.

3. Check and build

Section titled “3. Check and build”
Terminal window
pnpm check
pnpm build
pnpm run doctor
  • check checks TypeScript, the manifest and declared assets.
  • build produces the importable folder and checks its generated imports.
  • doctor checks the author environment. HOST_UNVERIFIED means a desktop trial is still needed.

Expect plugin.json, dist/index.js, view.css and LICENSE in package/. Builds can also include relative chunks and source maps. Plugin installation runs no compiler or npm scripts.

4. Run it in Lomi

Section titled “4. Run it in Lomi”
  1. Open a project folder and workspace in Lomi.
  2. Use Settings > Plugins > Import plugin and select my-plugin/package.
  3. Enable Workspace info, review its details and select Trust and enable.
  4. Open Commands and choose Workspace info. The default shortcut is Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows and Linux.
  5. Change Show project path. Run the command again: this template selects its existing panel in the same workspace.
  6. Switch workspaces and run the command again. That workspace gets a separate instance.

If you changed the Commands shortcut in Settings > Keybinds, use your configured shortcut. Import stores the package without running its code. Read Installing and managing plugins for trust and management details.

5. Make your first change

Section titled “5. Make your first change”

In src/index.tsx, change Appearance: to Current appearance:. Run:

Terminal window
pnpm check
pnpm build

Disable the old plugin in Settings > Plugins, import package/ again and approve the changed revision. If Restart required appears, use Restart Lomi and resolve unsaved work.

Lomi uses a copy of the package. Editing source or rebuilding the folder does not update a running plugin. This tooling version has no dev, live reload or file watcher. A failed build keeps the last good package/; check the command result before importing it.

6. Prepare a package to share

Section titled “6. Prepare a package to share”
Terminal window
pnpm package

For the template’s 0.1.0 version, this creates:

artifacts/
├── example.workspace-info-0.1.0.zip
├── example.workspace-info-0.1.0.sha256
└── example.workspace-info-0.1.0.validation.json

Recipients extract the ZIP and import the folder containing plugin.json. Increase version in plugin.json for the next release: the CLI does not overwrite existing artifacts. See Packaging and troubleshooting for the complete workflow.

Next steps

Section titled “Next steps”
Your goal Guide
Choose a sidebar, command or theme Templates and project structure
Understand every plugin.json field Manifest
Use the methods available in activate() SDK and lifecycle
Save preferences or protect edited documents Views and state
Add a shortcut or status bar button Commands and interface contributions
Include CSS, images and themes Styles and assets
Prepare a desktop release Desktop qualification
Build without the CLI Manual SDK example