Skip to content
Eidos Docs

Create your first plugin

Start with the Eidos plugin template. It contains a working page, a command to open it, theme styles, tests, and a GitHub Actions workflow. You will open its counter, change its behavior, and build an installable package.

You need Node.js 22.12 or later, npm, Git, and Eidos Lite with Plugin API 3.0.0 or later. Prepare a test Space. The template pins published SDK/tools dependencies; you do not need the Eidos source repository or a development server.

1. Create your repository

Section titled “1. Create your repository”

Open the template and choose Use this template → Create a new repository. Name it my-eidos-plugin, then clone your new repository. Replace YOUR-NAME with its GitHub owner:

Terminal window
git clone https://github.com/YOUR-NAME/my-eidos-plugin.git
cd my-eidos-plugin
npm ci
plugin.json                   Identity and contributions
src/main.ts                   The page interface
src/extension.ts              The command that opens the page
src/style.css                 Host theme styles
test/plugin.test.ts           Interaction and cleanup tests
.github/workflows/plugin.yml  Check, package and release workflow

2. Give the plugin its own identity

Section titled “2. Give the plugin its own identity”

Edit these fields in the existing plugin.json, keeping the other declarations:

Field Example
id yourname.my-counter
name My Counter
description A counter for my workspace
views[0].title My Counter
actions[0].title My Counter: Open

IDs use lowercase segments separated by dots. Choose your own namespace and keep the ID stable after distribution. Preserve contribution IDs main and open, which the command and placements reference.

Change package.json’s name to your project name, then run npm install --package-lock-only to update the lockfile. Keep the version fields in both manifests at 0.1.0 for this exercise. requires.pluginApi declares the minimum API the code uses; raising it alone does not add a capability.

3. Check and open the page

Section titled “3. Check and open the page”
Terminal window
npm run typecheck
npm test
npm run check

These commands check TypeScript, test page/command lifecycle, and validate declarations and Lite compatibility. A successful check does not exercise the host UI; open the plugin next:

  1. Open your test Space in Eidos Lite and go to Plugin Manager.
  2. Choose Load development source… and select your project’s plugin.json.
  3. Review the declarations and enable the plugin for this Space.
  4. Open My Counter from navigation, or use Cmd/Ctrl+K → My Counter: Open.

The page shows Add one and 0. Click twice; the count should be 2. The starter requests no file, network, storage, or background access. Its page and command target Lite; CLI Serve does not support these entry points.

4. Change the behavior

Section titled “4. Change the behavior”

Open src/main.ts. mount(ctx, root) builds the interface inside the host’s container. Change its heading to your own text, then make every click add five:

const increment = () => {
  value += 5
  count.textContent = String(value)
}

Save the file. Lite recompiles and reloads the source. The counter starts at 0 again; click once and check that it shows 5. Update the test’s expected counts if you keep this change, then rerun the checks.

The counter is page-local memory and resets when the page closes or reloads. ctx.subscriptions releases its listeners when the scope closes. src/extension.ts registers open and uses the command invocation’s ctx.capabilities.ui.navigate("main", "/") to open the page.

If compilation fails, Lite keeps the last working revision visible. Fix the compiler error before assuming your change has loaded. Match the host theme with the --eidos-* variables used in src/style.css.

5. Build an installable package

Section titled “5. Build an installable package”

After the checks pass, run:

Terminal window
npm run pack:plugin

With the example ID, the outputs are:

dist/yourname.my-counter-0.1.0.eidos-plugin
dist/yourname.my-counter-0.1.0.eidos-plugin.sha256

Install the archive through Plugin Manager, review its declarations, enable it, and reopen the page. Development loading is temporary; installing the package keeps that revision available after restart.

The repository’s Actions workflow runs the checks and uploads a plugin-package artifact. A matching version tag creates a GitHub Release only after checks pass. Read development and distribution before publishing or submitting the plugin to the registry.

Next steps

Section titled “Next steps”