# Plugins

Plugins are JavaScript that runs inside Thymer. A few lines add a command to the palette, a computed property to a collection, or a whole custom view. The [Plugin SDK](https://github.com/thymerapp/thymer-plugin-sdk) has typed declarations, examples and a hot-reload development loop, and [awesome-thymer-plugins](https://github.com/ed-nico/awesome-thymer) lists plugins the community has shared. For more about plugins, see [thymer.com/plugins](https://thymer.com/plugins/).

## Two kinds

An **app plugin** extends the workspace: command palette commands, status bar items, sidebar widgets, notifications, custom panels. Its class extends `AppPlugin`.

A **collection plugin** extends one collection: formulas, custom property rendering and sorting, custom views, buttons on board cards. Its class extends `CollectionPlugin`, and it has `this.collection`, `this.properties` and `this.views` on top of the shared APIs. Every collection has a plugin behind it; **Edit Code** in Collection Settings opens it. Dynamic collections use `DynCollectionPlugin`.

## Install a plugin

Workspace admins add plugins in the **Plugins** panel: **Plugins** in the command palette, or **Settings → Plugins**. The panel has two tabs, **Global Plugins** for app plugins and **Collections** for collection plugins.

### From a link

Most shared plugins live on GitHub, and Thymer installs them from their link:

1. Copy the link to the plugin's repository, such as `https://github.com/author/plugin`.
2. In the Plugins panel, open **Add plugin** and choose **Install from URL**.
3. Paste the link and click **Load Plugin**. Thymer downloads the plugin and shows its name, type, version, author and description. Nothing runs yet.
4. Click **Open Draft**. The plugin opens in the code editor as a draft: a new global plugin, or a new collection for a collection plugin.
5. Click **Preview** to run it, then **Save** to keep it. **Discard** removes the draft.

A repository link works when the plugin's files are at the top of a public repository: a `thymer-plugin.json`, or a `plugin.json` with a ready-to-run `plugin.js`. For a plugin somewhere else in a repository, open its `thymer-plugin.json` on GitHub and paste the link from the address bar; the **Raw** link works too. If a plugin has to be built first, follow its author's instructions.

**More about plugins** in the same menu opens [thymer.com/plugins](https://thymer.com/plugins/).

### Updates

**Check for updates** in the Plugins panel asks each plugin you installed from a link whether there is a newer version. Thymer never updates a plugin by itself. A plugin with a newer version shows **Update**, which opens the same review: **Open Draft**, **Preview**, **Save**, or **Discard** to keep the version you have.

Your settings in the plugin's configuration are kept, and new ones are added. If you changed the plugin's code yourself, Thymer warns you before replacing it. Plugins you pasted in by hand aren't checked, and neither are plugins whose author gives no version number.

### By hand

**Add plugin → Create a plugin** opens the code editor with three parts: **Configuration**, a small JSON with the name, icon and description; **Custom Code**, the JavaScript; and **Custom CSS** for styling. Paste what the plugin's author gave you, **Preview**, and save when it works. A switch on each plugin turns it off without deleting it.

Code pasted into the app starts with `class Plugin extends AppPlugin` or `CollectionPlugin`; an `export` in front is fine. Code with `import` lines comes from the SDK and has to be bundled first: paste the bundled `dist/plugin.js`.

## What to know before installing

Plugins run in your signed-in app with the same access you have, and their code and configuration are stored in the workspace, where every member can read them. Read a plugin before installing it, especially anything that makes network requests, and keep API keys out of shared plugin code. The CLI can read and update plugins too; see [The CLI](ai-agents-and-cli/the-cli.md).

**Preview** runs the plugin's code. **Discard** removes a draft or puts the previous version back, but doesn't undo what the plugin did while it ran. If a plugin makes Thymer hard to use, [Safe Mode](help/troubleshooting.md#safe-mode) starts Thymer without plugin code.

- [Your first plugin](plugins/your-first-plugin.md): a palette command in ten lines.
- [Collection plugins](plugins/collection-plugins.md): configuration, fields, views and the hooks for custom views and properties.
- [Developing with the SDK](plugins/developing-with-the-sdk.md): hot reload from your editor, bundling, examples and troubleshooting.
- [Plugin API reference](plugins/plugin-api-reference.md): the main objects and methods.