This quickstart walks you through cloning the Zotero Connectors repository, installing dependencies, running a development build, and loading the resulting unpacked extension into Chrome or Firefox so you can see your changes live. By the end you will have a working local copy of the extension that rebuilds automatically as you edit source files.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.
Prerequisites
Before you begin, make sure the following are installed on your machine:- Git — with support for
--recursivesubmodule cloning. The repository depends on several Git submodules (Zotero Translate, Zotero Utilities, SingleFile-Lite, and others) that must be checked out alongside the main repo. - Node.js — any actively-supported LTS release (v18 or later recommended).
- npm — bundled with Node.js; used to install the Gulp build system and all other dev dependencies.
If you already cloned the repository without
--recursive, you can initialise the submodules afterwards by running git submodule update --init --recursive from the project root.Steps
Clone the repository with submodules
Use
--recursive to check out all required Git submodules in one command:Install Node.js dependencies
Install the Gulp build system, Babel, React, and all other development dependencies declared in
package.json:Build for development
Run the build script with the The connectors are compiled into the
-d flag to produce a debug build:build/ directory. Two subdirectories are produced for browser extensions:| Directory | Target |
|---|---|
build/firefox/ | Firefox (Manifest V2) |
build/manifestv3/ | Chrome / Edge (Manifest V3) |
Load the extension in your browser
Choose your browser below and follow the corresponding steps to sideload the unpacked build:Once loaded, the Zotero Connector toolbar button will appear in your browser. You can click it on any supported page to save references.
Verify the extension is working
Navigate to a page with bibliographic metadata — for example, a journal article on PubMed or a book listing on a library catalogue. The Zotero Connector toolbar button should change icon to reflect the detected reference type (article, book, etc.). Click it to trigger a save.If Zotero is running on your machine, the item will be saved to your library via the connector server on port
23119. If Zotero is not running, the connector will offer to save to your zotero.org account instead.Automatic Rebuilding with gulp watch
After the initial build, you can keep the extension in sync with your source edits automatically. From the project root, run:
src/browserExt/, src/common/, src/safari/, and src/zotero-google-docs-integration/src/connector/ and rebuilds the affected output whenever a file changes. After each rebuild you will need to manually reload the extension in the browser:
- Chrome/Edge — click the reload icon (↺) next to the extension on
chrome://extensions/. - Firefox — click “Reload” next to the extension on
about:debugging.
gulp watch is the alias for the default Gulp task. You can also run npx gulp watch if gulp is not on your PATH.Safari
Safari support is maintained in a separate repository and requires additional macOS tooling. See github.com/zotero/safari-app-extension for build and loading instructions specific to the Safari App Extension. The
build.sh -p s flag targets the Safari build locally, but the resulting artifact must be bundled through the safari-app-extension Xcode project before it can be loaded.Packaging for Release
Packaging signed extension archives for distribution requires additional configuration. Copyconfig.sh-sample to config.sh and fill in the required credentials (extension signing keys, S3 bucket, deploy host, etc.) before running build.sh without the -d flag. See the comments in config.sh-sample for details on each variable.