thymer docs
Documentation/Plugins/Developing with the SDK

Developing with the SDK

For anything beyond a few lines, use the 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:
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/thymer-dev --no-first-run https://myaccount.thymer.com
  1. In that browser, open the plugin’s code editor, select the Developer Tools tab, and click Enable Plugin Hot Reload.
  2. 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.

{
  "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.