Zotero Connectors are the open-source browser extensions that let researchers save bibliographic references directly from any web page into their Zotero library. This documentation is intended for developers who want to build, extend, audit, or simply understand the Zotero Connectors codebase — whether that means adding support for a new site, fixing a bug, contributing a feature, or studying how the translation pipeline works end-to-end.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zotero/zotero-connectors/llms.txt
Use this file to discover all available pages before exploring further.
Supported Browsers
Zotero Connectors target four browsers through two distinct codebases:| Browser | Extension Framework | Build target |
|---|---|---|
| Chrome | WebExtension API — Manifest V3 | build/manifestv3 |
| Firefox | WebExtension API — Manifest V2 | build/firefox |
| Edge | WebExtension API — Manifest V3 (same build as Chrome) | build/manifestv3 |
| Safari | Safari App Extension (separate repository) | See safari-app-extension |
Chrome and Edge share the same Manifest V3 build output. Firefox uses the Manifest V2 build, which retains
webRequestBlocking and the applications gecko field that Firefox requires. Safari is maintained in its own repository at github.com/zotero/safari-app-extension.Runtime Architecture
The Zotero Connector splits its logic across two major runtime contexts inside each browser:a) Injected Content Scripts
Every web page visited by the user is injected — atdocument_start — with the full Zotero translation framework. A Zotero.Translate.Web instance orchestrates running individual translators for site detection and item extraction. Custom classes handle translator retrieval and item saving, delegating work that requires privileged APIs to the background process via message passing.
b) Background Process
A persistent background process (a service worker in Manifest V3, a background script in Manifest V2) acts as the middle layer between the content scripts and the save targets. It maintains a translator cache, performs initial URL-pattern-based translator detection, manages extension UI state, handles connector preferences, and dispatches translated items to either the Zotero desktop client or the zotero.org web API. The only communication channel between content scripts and the background process is the browser’s native message-passing protocol. To simplify this, background-process method calls are monkey-patched in injected scripts so that they appear synchronous while executing asynchronously over the message bridge.Save Targets
Translated items can be sent to one of two destinations:- Zotero Desktop Client (port 23119) — When Zotero is running, the connector communicates with its built-in connector HTTP server on
localhost:23119. All communication is Connector-initiated; Zotero itself cannot push data to the extension. - zotero.org Web API — When the desktop client is not available, the connector falls back to saving items via the zotero.org REST API (v3), defined in
src/common/api.js.
Key Technologies
| Technology | Role |
|---|---|
| WebExtension API | Cross-browser extension platform (Chrome/Firefox/Edge) |
| Zotero Translate framework | Translator detection, execution, and item extraction (github.com/zotero/translate) |
| React 16 | UI components (progress window, modal prompts, preferences) |
| Gulp 4 | Build pipeline — JSX transpilation, script bundling, file watching |
| Babel | Transpiles JSX and modern JavaScript for extension contexts |
The Zotero Translate framework is included as a Git submodule under
src/translate. A working knowledge of how translators detect and extract bibliographic data is highly useful when contributing to the Connectors codebase.Where to Go Next
Quickstart
Clone the repository, build the extension with a single command, and load it as an unpacked extension in Chrome or Firefox in under five minutes.
Installation
Install the Zotero Connector from official browser extension stores, or learn how to sideload a development build for testing.
License
Zotero Connectors are released under the GNU Affero General Public License v3.0 (AGPL-3.0). See theCOPYING file in the repository root for the full license text.