# Developing with the SDK

For anything beyond a few lines, use the [Plugin SDK](https://github.com/thymerapp/thymer-plugin-sdk): you write in your own editor with type checking, and every save is pushed into a running Thymer.

## The loop

1. Clone the SDK and run `npm install`. `plugin.js` and `plugin.json` are your plugin; `types.d.ts` documents the API.
2. Start Chrome with a debugging port and a separate profile, and open your account in it:

```bash
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/thymer-dev --no-first-run https://myaccount.thymer.com
```

3. In that browser, open the plugin's code editor, select the **Developer Tools** tab, and click **Enable Plugin Hot Reload**.
4. Run `npm run dev`. The SDK bundles your code and pushes it to the browser on every save. `npm run dev:verbose` prints the bundle as well.

Hot reload is a preview. When you are done, `npm run build` writes `dist/plugin.js`, without the source maps the dev loop adds. Paste it into **Custom Code** and `plugin.json` into **Configuration**, then **Preview** and save.

## Share a plugin

To let others install your plugin from its link, publish it in a public GitHub repository with a `thymer-plugin.json` next to its files. This file describes the package; `plugin.json` stays the plugin's configuration.

```json
{
  "manifestVersion": 1,
  "id": "yourname.task-timer",
  "name": "Task Timer",
  "author": "Your name",
  "version": "1.0.0",
  "type": "global",
  "description": "Track time on tasks",
  "files": {
    "config": "plugin.json",
    "js": "dist/plugin.js"
  }
}
```

- `manifestVersion`, `id`, `name`, `author`, `version`, `type` and `files.config` are required. `description`, `homepage`, `screenshot`, `files.js` and `files.css` are optional.
- `type` is `global` for an app plugin or `collection` for a collection plugin.
- `id` stays the same for the life of the plugin. Start it with your name, and use lowercase letters, numbers, dots, hyphens and underscores.
- `version` is three numbers, such as `1.2.0`. It is your release number, not the configuration's `ver`.
- `files.js` points to code that runs as it is. Thymer doesn't build anything, so publish `dist/plugin.js` from `npm run build`, even if your repository ignores `dist/`.
- `files.config` holds defaults only: no personal settings or API keys. `custom` is an object, such as `{}`.
- Paths are relative to `thymer-plugin.json`. Images and other files that your CSS or code loads need full HTTPS links or embedded data.

With `thymer-plugin.json` at the top of the repository, people paste the repository link into **Install from URL**. Anywhere else, they paste the file's link on GitHub, or its **Raw** link. Any HTTPS host works too, if it allows cross-origin requests. The code, CSS and configuration may take 5 MB together, CSS and configuration 1 MB each.

### New versions

1. Publish the new files first, or together with the manifest.
2. Raise `version` in `thymer-plugin.json`, also for a change to the CSS or the configuration only.
3. Keep the manifest's link, the `id` and the `type` the same, and keep field and view ids stable, so people's settings carry over.

Installed copies see the new version when their admins click **Check for updates**. A link to a fixed commit or tag stays on that release.

## Examples

The SDK's `examples/` folder has app plugins and collection plugins to start from: a simple list view, buttons on kanban cards, a work-in-progress limit, kanban dependencies, custom choice dropdowns, an organization chart. Most examples come with a `thymer-plugin.json`: paste that file's link on GitHub into **Install from URL**. The SDK repository link alone won't work, because it holds many plugins. The examples guide in the folder lists them, with what to try after installing. To build on one, copy it into the SDK project, change the field and view ids to yours, and try it on a few real pages.

## When something is off

- Nothing happens: check that the plugin is enabled, then look for errors in the editor and in the browser console.
- Pasted code fails: in-app code uses `class Plugin`, without `import` lines. Bundle SDK code first.
- A field or view is missing: it needs both a configuration entry, with `"type": "custom"` for views, and a matching registration in the code.
- Hot reload stops: check that `npm run dev` is running, the browser was started with the debugging port, and hot reload is enabled on this plugin.
- Thymer gets slow: look for timers and listeners that survive `onUnload()`, scans of the whole workspace, and views that rebuild the DOM on every refresh.

Disable the plugin while you investigate. If you need help, send a small plugin that reproduces the problem along with your description; see [Reporting a bug](../help/troubleshooting.md#reporting-a-bug).