====== Zotero 7 for Developers ====== Zotero 7, which will be released in 2024, includes a major internal upgrade of the Mozilla platform on which Zotero is based, incorporating changes from Firefox 60 through Firefox 115. This upgrade brings major performance gains, new JavaScript and HTML features, better OS compatibility and platform integration, and native support for Apple Silicon Macs. While this upgrade required a massive rewrite of the Zotero code base and will require many plugin changes due to technical changes in the Mozilla platform, going forward we expect to keep Zotero current with Firefox Extended Support Release (ESR) versions, with comparatively fewer technical changes between versions. ===== Feedback ===== If you have questions about anything on this page or encounter other problems while updating your plugin, let us know on the [[https://groups.google.com/g/zotero-dev|dev list]]. Please don't post to the Zotero Forums about Zotero 7 at this time. ===== Dev Builds ===== WARNING: These are test builds based on Firefox 115 intended solely for use by Zotero plugin developers and **should not be used in production**. We strongly recommend using a [[https://www.zotero.org/support/kb/multiple_profiles|separate profile and data directory]] for development. * [[https://www.zotero.org/download/client/dl?channel=dev&platform=mac|Mac]] * [[https://www.zotero.org/download/client/dl?channel=dev&platform=linux-x86_64|Linux 64-bit]] * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win-x64-zip|Windows 64-bit ZIP]] * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win-x64|Windows 64-bit Installer]] * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win32-zip|Windows 32-bit ZIP]] * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win32|Windows 32-bit Installer]] ===== Sample Plugin ===== We've created a very simple plugin, [[https://github.com/zotero/make-it-red|Make It Red]], to demonstrate some of the concepts discussed in this document. It makes things red. We'll update the plugin as we continue developing the Zotero 7 plugin framework and address issues from the dev list. ===== Using the Firefox Developer Tools ===== Since Zotero 7 is based on Firefox 115, it's compatible with the [[https://ftp.mozilla.org/pub/firefox/releases/115.9.1esr/|Firefox 115 ESR]] Developer Tools (rather than the Firefox 60 DevTools as before). To start a Zotero dev build with the DevTools server, pass the ''-debugger'' flag on the command line:


$ /Applications/Zotero\ Dev.app/Contents/MacOS/zotero -ZoteroDebugText -jsconsole -debugger

In Firefox 115 ESR, you can then go to about:debugging, add ''localhost:6100'' as a network location, and connect to Zotero. (If you haven't yet, you'll first need to enable the "Enable browser chrome and add-on debugging toolboxes" and "Enable remote debugging" options in the settings of Firefox's Web Developer Tools.) You should use a separate Firefox profile for 115 ESR and disable automatic updates to prevent Firefox from being automatically updated to an incompatible version. ===== Plugin Changes ===== **All Zotero plugins will need to be updated for Zotero 7.** Zotero 7 plugins continue to provide full access to platform internals (XPCOM, file access, etc.), but the Mozilla platform itself no longer supports similar extensions. All Firefox extensions are now based on the much more limited WebExtensions API shared with Chrome and other browsers, which provides sandboxed APIs for common integration points. We have no plans to make similar restrictions in Zotero. However, due to the Mozilla platform changes, some integration techniques are no longer available, and all plugins will need to change the way they register themselves in Zotero. ==== install.rdf → manifest.json ==== The legacy install.rdf manifest must be replaced with a [[https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json|WebExtension-style manifest.json file]]. Most WebExtension manifest.json keys are not relevant in Zotero, but you should transfer the main metadata from install.rdf.

{
  "manifest_version": 2,
  "name": "Make It Red",
  "version": "1.1",
  "description": "Makes everything red",
  "author": "Zotero",
  "icons": {
    "48": "icon.png",
    "96": "icon@2x.png"
  },
  "applications": {
    "zotero": {
      "id": "make-it-red@zotero.org",
      "update_url": "https://www.zotero.org/download/plugins/make-it-red/updates.json",
      "strict_min_version": "6.999",
      "strict_max_version": "7.0.*"
    }
  }
}

''applications.zotero'' is based on ''[[https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings|browser_specific_settings.gecko]]'' and must be present for Zotero to install your plugin. You should set ''strict_max_version'' to ''x.x.*'' of the latest minor version that you have tested your plugin with. (You can later update compatibility via your update manifest without distributing a new version if no changes are required.) Use ''%%"strict_min_version": "6.999"%%'' to allow your plugin to be installed on Zotero 7 betas. === Transition Process === Plugins can be made to work in both Zotero 6 and Zotero 7 by including both install.rdf and manifest.json files. Zotero 6 will use install.rdf, while Zotero 7 will use manifest.json. You can load overlay code for Zotero 6 and bootstrap code (as described below) for Zotero 7, or you can create a single bootstrapped version by adding ''true'' to install.rdf for Zotero 6. ==== update.rdf → updates.json ==== The legacy RDF update manifest for specifying updates must be replaced with a [[https://extensionworkshop.com/documentation/manage/updating-your-extension/|Mozilla-style JSON update manifest]]:

{
  "addons": {
    "make-it-red@zotero.org": {
      "updates": [
        {
          "version": "2.0",
          "update_link": "https://download.zotero.org/plugins/make-it-red/make-it-red-2.0.xpi",
          "update_hash": "sha256:4a6dd04c197629a02a9c6beaa9ebd52a69bb683f8400243bcdf95847f0ee254a",
          "applications": {
            "zotero": {
              "strict_min_version": "6.999"
            }
          }
        }
      ]
    }
  }
}

Zotero 6 also supports this manifest format with a slight variation: you must specify minimum and maximum versions using ''applications.gecko'' instead of ''applications.zotero'', and you must use the Firefox platform version instead of the Zotero app version. Since Zotero 6 is based on Firefox 60.9.0 ESR, you can use ''60.9'' for ''strict_min_version'' and ''strict_max_version''.

{
  "addons": {
    "make-it-red@zotero.org": {
      "updates": [
        {
          "version": "1.0",
          "update_link": "https://download.zotero.org/plugins/make-it-red/make-it-red-1.0.xpi",
          "update_hash": "sha256:8f383546844b17eb43bd7f95423d7f9a65dfbc0b4eb5cb2e7712fb88a41d02e3",
          "applications": {
            "gecko": {
              "strict_min_version": "60.9",
              "strict_max_version": "60.9"
            }
          }
        }
      ]
    }
  }
}

In this example, version 1.2 is compatible with both Zotero 6 and 7, and version 2.0 is compatible only with Zotero 7:

{
  "addons": {
    "make-it-red@zotero.org": {
      "updates": [
        {
          "version": "1.2",
          "update_link": "https://download.zotero.org/plugins/make-it-red/make-it-red-1.2.xpi",
          "update_hash": "sha256:9b0546d5cf304adcabf39dd13c9399e2702ace8d76882b0b37379ef283c7db13",
          "applications": {
            "gecko": {
              "strict_min_version": "60.9",
              "strict_max_version": "60.9"
            },
            "zotero": {
              "strict_min_version": "6.999",
              "strict_max_version": "7.0.*"
            }
          }
        },
        {
          "version": "2.0",
          "update_link": "https://download.zotero.org/plugins/make-it-red/make-it-red-2.0.xpi",
          "update_hash": "sha256:4a6dd04c197629a02a9c6beaa9ebd52a69bb683f8400243bcdf95847f0ee254a",
          "applications": {
            "zotero": {
              "strict_min_version": "6.999",
              "strict_max_version": "7.0.*"
            }
          }
        }
      ]
    }
  }
}

=== Transition Process === Since Zotero 6 already supports the new JSON update manifest, we recommend creating a JSON manifest now and pointing new versions of your plugin at its URL in install.rdf, even before you've updated your plugin for Zotero 7. As described above, you can serve a manifest that offers a version that supports only Zotero 6 now and later add a version that supports both Zotero 6 and 7 and/or a version that supports only Zotero 7, all from the same file. However, since you can't be sure that all of your users will upgrade to your new version that points to a JSON URL before they upgrade to Zotero 7, and since Zotero 7 will no longer be able to parse RDF update manifests, there's a risk of users getting stranded on an old version. To avoid this, you can simply make the new JSON manifest available from the old RDF URL as well. Even with the .rdf extension, Zotero will detect that it's a JSON manifest and process it properly. ==== XUL Overlays → bootstrap.js ==== This will likely be the biggest change for most plugin developers. Zotero 6 and earlier supported two types of plugins: - Overlay plugins, which use XUL overlays to inject elements — including ''