keeweb

Table of Contents

How to create KeeWeb plugins
Examples
Manifest
Plugin contents
Locales
JS API
Settings
Guidelines
Contribution

How to create KeeWeb plugins

KeeWeb Plugin Creation Tool is the easiest way to start, here's it:
https://plugins.keeweb.info/create.html

To sign and use your plugin, you will need keeweb-plugin npm package:

$ npm i -g keeweb-plugin

Don't want to install it? Here's the script, you can just download it.

Important: plugin creation tool generates a private key for your plugin, you will have to keep it secure, to be able to update your plugin later.
To sign the resources inside your plugin and update the manifest, use:

$ keeweb-plugin sign my-awesome-plugin

Or watch and sign on changes:

$ keeweb-plugin watch my-awesome-plugin
KeeWeb plugin utils v0.1.8
This is your plugin URL for keeweb: https://127.0.0.1:8089
But first, open it in browser and click Proceed on unsafe website warning screen
Waiting for changes...

Now add your plugin to KeeWeb with this url: https://127.0.0.1:8089.

Examples

Plugin examples: https://github.com/keeweb/keeweb/tree/develop/plugins/examples

Real-world plugins are here.

Manifest

All plugins must have manifest.json. This file is generated by keeweb plugin generator script. Typical structure:

{
  "version": "0.0.1",
  "manifestVersion": "0.1.0",
  "name": "my-awesome-plugin",
  "description": "My asweome plugin",
  "author": {
    "name": "user",
    "email": "user@example.com",
    "url": "http://example.com"
  },
  "licence": "MIT",
  "url": "https://example.com/about_my_plugin",
  "resources": {
    "js": "<signature>",
    "css": "<signature>"
  },
  "publicKey": "<public_key>",
  "desktop": false,
  "versionMin": null,
  "versionMax": null
}

Locale plugins have additional section in manifest:

{
  ...other fields
  "resources": {
    "loc": "<signature>"
  },
  "locale": {
    "name": "nl-NL",
    "title": "Nederlands"
  }
}

As well as theme plugins:

{
  ...other fields
  "resources": {
    "css": "<signature>"
  },
  "theme": {
    "name": "rainbow",
    "title": "Rainbow"
  }
}

Theme class name will be th-rainbow in this case.

Plugin contents

Plugin can contain other files, depending on plugin type:

JS:
- plugin.js
JS+CSS:
- plugin.js
- plugin.css
CSS:
- plugin.css
Themes:
- plugin.css
Locales:
- <locale_name>.json

There's no possibility to customize script and style name. However you can use any builder to make output plugin.js and plugin.css files.

Locales

Basically you don't want to create a locale, unless you have a reason to do it. All locales are managed at OneSky and uploaded to plugins.keeweb.info. But if you need something special, you can create it, of course.

JS API

Plugins can use require and module.exports.
Example plugin script:

// you can use all KeeWeb modules
var _ = require('underscore');
var kdbxweb = require('kdbxweb');
var DetailsView = require('views/details/details-view');

module.exports.uninstall = function() {
  // It's necessary to have this function
  // Cleanup all plugin resources and overrides here
};

There's no public API, later it could be created for some common extension points, like fields, storages and so on. Now you can just override or extend KeeWeb modules.

Settings

Plugins can have settings, they will look like this:

There are three types of settings:

text
select
checkbox

To add settings, export two functions:

getSettings must return settings config: example
setSettings will be called every time settings are modified or after plugin load, with changed values: example

Guidelines

initialization should not take long, it's better to lazy-load stuff
take everything with you, don't read resources from network
revert all changes in uninstall function
use common sense: KeeWeb has no plugin API, plugins extend KeeWeb by augmenting its functions; don't go crazy, to be able to maintain your plugin in new versions, if you feel that something is too hard to extend, it's better to submit a PR or ask for a feature
think about compatibility: kdbx format should be compatible with all other clients

Contribution

3rd-party plugins will not be added to KeeWeb without a prior approval and review. If you would like to contribute a plugin, please open a pull request in keeweb-plugins repo.

The only official web app is https://app.keeweb.info