Zotero Connectors Build and Configuration Reference

Zotero Connector configuration lives at two layers: build-time settings that control what goes into each built artifact (flags passed to build.sh, options consumed by gulpfile.js, and secrets in config.sh), and runtime constants baked into every build via zotero_config.js (the ZOTERO_CONFIG object). Understanding both layers is necessary when cutting a release, customizing a build for local development, or wiring up a new deployment target.

build.sh Flags

build.sh is the top-level entry point for all connector builds. It coordinates resource copying, calls npx gulp for script processing, and assembles the per-browser output directories under build/.

Usage: ./build.sh [-p PLATFORMS] [-v VERSION] [-d]

string

A string of platform character codes specifying which platforms to build. Characters can be combined (e.g., -p bs builds both).

Character	Platform
`b`	Browser extension (produces `build/firefox/`, `build/manifestv3/`)
`s`	Safari (produces `build/safari/`)

Defaults to all platforms (b and s) when omitted.

string

Sets the connector version string embedded in manifests and zotero.js. Injected into manifest.json via "version": "AUTOFILLED" replacement and into zotero.js via this.version replacement.Defaults to 4.999.0 when omitted (also the gulp default).

boolean

Debug mode. When set:

The translator tester tool (tools/testTranslators/) is included in the build
Test libraries (mocha, chai, sinon, bluebird) are copied into build/*/lib/
The test/ directory is retained in the output
Gulp is invoked without the -p (production) flag, so minification is skipped

boolean

Prints usage information and exits.

Examples:

# Debug build of the browser extension only, version 5.0.100
./build.sh -d -p b -v 5.0.100

# Production build of all platforms at the default version
./build.sh

# Safari-only release build
./build.sh -p s -v 5.0.100

build.sh sources config.sh (if it exists) before running. Variables set in config.sh override defaults used during packaging and deployment steps.

gulpfile.js Options

gulpfile.js is invoked by build.sh via npx gulp process-custom-scripts. It handles JSX transpilation (via Babel), browser-specific replacements, script list injection into manifests, and source map generation. Arguments are parsed with yargs.

boolean

default:"false"

Production mode. When true:

The translator tester inject scripts (translatorTester_messages.js, translatorTester_inject.js) are excluded from injected script lists
The translator tester background script (translatorTester_background.js) is excluded from background script lists
The test inject file (test/testInject.js) is excluded from the MV3 inject list
... HTML comment blocks are stripped from HTML files

Shorthand: -p

string

default:"4.999.0"

Sets the version string injected into manifest.json files (replacing the "version": "AUTOFILLED" sentinel) and into zotero.js (replacing the this.version assignment). Passed through from build.sh’s -v VERSION flag.

Invoked by build.sh as:

# Debug build
npx gulp process-custom-scripts --connector-version "$VERSION"

# Production build
npx gulp process-custom-scripts --connector-version "$VERSION" -p

config.sh Variables

config.sh is sourced by build.sh when present. It is never committed to source control — it contains signing credentials and deployment secrets. The repository provides config.sh-sample as a template:

#!/bin/sh
ROOT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

FIREFOX_UPDATE_URL="https://example.com/download/connector/firefox/CHANNEL/updates.json"

export WEB_EXT_API_KEY=""
export WEB_EXT_API_SECRET=""
export CHROME_EXTENSION_KEY=""
S3_BUCKET="foo-download"
DEPLOY_HOST="deploy.local"
MANIFEST_DEPLOY_PATH="/path/to/dir"
DEPLOY_CMD="/path/to/script"

ZOTERO_GOOGLE_DOCS_DEV_MODE=
ZOTERO_GOOGLE_DOCS_API_URL_BETA=
ZOTERO_GOOGLE_DOCS_OAUTH_CLIENT_KEY_BETA=

Variable	Description
`FIREFOX_UPDATE_URL`	URL template for Firefox extension update manifests (`updates.json`). Used when packaging the Firefox XPI for self-hosted distribution.
`WEB_EXT_API_KEY`	AMO (addons.mozilla.org) API key for signing Firefox XPIs via `web-ext sign`. Exported so `web-ext` picks it up from the environment.
`WEB_EXT_API_SECRET`	AMO API secret, paired with `WEB_EXT_API_KEY`.
`CHROME_EXTENSION_KEY`	Chrome/Edge extension public key injected into `manifest.json` (MV3 only) as the `"key"` field. Used during development to keep the extension ID stable. Set via `process.env.CHROME_EXTENSION_KEY` in `gulpfile.js`.
`S3_BUCKET`	S3 bucket name used by the deployment step to host XPI downloads.
`DEPLOY_HOST`	Hostname of the deployment server for rsync/SSH operations.
`MANIFEST_DEPLOY_PATH`	Remote filesystem path where Firefox update manifests are deployed.
`DEPLOY_CMD`	Path to the deployment trigger script run after artifact upload.
`ZOTERO_GOOGLE_DOCS_DEV_MODE`	When non-empty, enables Google Docs dev mode (uses beta Apps Script endpoint).
`ZOTERO_GOOGLE_DOCS_API_URL_BETA`	Beta Google Apps Script endpoint URL, used in dev mode.
`ZOTERO_GOOGLE_DOCS_OAUTH_CLIENT_KEY_BETA`	OAuth client key for the beta Google Apps Script endpoint.

Never commit config.sh to source control. It contains AMO signing credentials (WEB_EXT_API_KEY, WEB_EXT_API_SECRET) and other secrets. The file is listed in .gitignore. Copy config.sh-sample to config.sh and fill in real values locally or in your CI secrets store.

ZOTERO_CONFIG Constants

src/common/zotero_config.js defines the ZOTERO_CONFIG constant object, which is bundled into every build. It contains all runtime URLs, OAuth credentials, and feature flags. Values here are baked in at build time and cannot be changed at runtime without rebuilding.

const ZOTERO_CONFIG = {
  CLIENT_NAME: 'Zotero',
  DOMAIN_NAME: 'zotero.org',
  SETTINGS_URL: 'https://repo.zotero.org/settings',
  REPOSITORY_URL: 'https://repo.zotero.org/repo/',
  REPOSITORY_CHECK_INTERVAL: 86400, // 24 hours in seconds
  REPOSITORY_RETRY_INTERVAL: 3600,  // 1 hour in seconds
  REPOSITORY_CHANNEL: 'trunk',
  ALWAYS_FETCH_FROM_REPOSITORY: false,
  BASE_URI: 'https://zotero.org/',
  WWW_BASE_URL: 'https://www.zotero.org/',
  CLIENT_DOWNLOAD_URL: 'https://www.zotero.org/download',
  API_URL: 'https://api.zotero.org/',
  GOOGLE_DOCS_API_URL: "https://script.googleapis.com/v1/scripts/AKfycbzCBCyrm1hnQJDEckGkOJabbhv4SO7udII0SK5BoKbgJLxy5I6A5LiGZ_xAZ-eOYEIJuw:run",
  OAUTH: {
    ZOTERO: {
      REQUEST_URL: 'https://www.zotero.org/oauth/request',
      ACCESS_URL:  'https://www.zotero.org/oauth/access',
      AUTHORIZE_URL: 'https://www.zotero.org/oauth/authorize',
      CALLBACK_URL: 'https://www.zotero.org/connector_auth_complete',
      CLIENT_KEY:    '05a4e25d3d9af8922eb9',
      CLIENT_SECRET: '8dda1d6aa188bdd3126e'
    },
    GOOGLE_DOCS: {
      AUTHORIZE_URL: 'https://accounts.google.com/o/oauth2/v2/auth',
      ACCESS_URL:    'https://www.googleapis.com/oauth2/v3/tokeninfo',
      CALLBACK_URL:  'https://www.zotero.org/connector_auth_complete',
      CLIENT_KEY:    '222339878061-13uqre19u268oo9pdapuaifklbu8d6js.apps.googleusercontent.com'
    }
  },
  GOOGLE_DOCS_DEV_MODE: false
};

Constant	Type	Description
`CLIENT_NAME`	`string`	Display name for the Zotero application (`"Zotero"`). Used in UI strings.
`DOMAIN_NAME`	`string`	Base domain for Zotero services (`"zotero.org"`).
`SETTINGS_URL`	`string`	URL of the Zotero settings/repository endpoint.
`REPOSITORY_URL`	`string`	Base URL of the translator repository (`https://repo.zotero.org/repo/`). Used for translator update requests and debug report submissions.
`REPOSITORY_CHECK_INTERVAL`	`number`	How often (in seconds) the connector checks for translator updates. Default: `86400` (24 hours).
`REPOSITORY_RETRY_INTERVAL`	`number`	Retry interval (in seconds) after a failed repository check. Default: `3600` (1 hour).
`REPOSITORY_CHANNEL`	`string`	Translator repository channel to fetch from. Default: `"trunk"`.
`ALWAYS_FETCH_FROM_REPOSITORY`	`boolean`	When `true`, translator code is always fetched from the remote repository, bypassing the local Zotero desktop cache. Intended for debugging translator issues. Default: `false`.
`BASE_URI`	`string`	Base URI for Zotero web properties (`https://zotero.org/`).
`WWW_BASE_URL`	`string`	Base URL for the Zotero website (`https://www.zotero.org/`).
`CLIENT_DOWNLOAD_URL`	`string`	URL where users are directed to download the Zotero desktop client.
`API_URL`	`string`	Base URL for the Zotero Web API (`https://api.zotero.org/`). Used by `Zotero.API` methods.
`GOOGLE_DOCS_API_URL`	`string`	Google Apps Script deployment URL for the Zotero Google Docs integration backend.
`OAUTH.ZOTERO.REQUEST_URL`	`string`	OAuth 1.0a request token endpoint.
`OAUTH.ZOTERO.ACCESS_URL`	`string`	OAuth 1.0a access token endpoint.
`OAUTH.ZOTERO.AUTHORIZE_URL`	`string`	OAuth 1.0a user authorization URL (opened in a browser window).
`OAUTH.ZOTERO.CALLBACK_URL`	`string`	OAuth callback URL — the connector listens for navigation to this URL to detect authorization completion.
`OAUTH.ZOTERO.CLIENT_KEY`	`string`	OAuth consumer key for the Zotero connector application.
`OAUTH.ZOTERO.CLIENT_SECRET`	`string`	OAuth consumer secret for the Zotero connector application.
`OAUTH.GOOGLE_DOCS.AUTHORIZE_URL`	`string`	Google OAuth 2.0 authorization endpoint.
`OAUTH.GOOGLE_DOCS.ACCESS_URL`	`string`	Google OAuth 2.0 token info endpoint.
`OAUTH.GOOGLE_DOCS.CALLBACK_URL`	`string`	Google OAuth callback URL (same as Zotero OAuth callback).
`OAUTH.GOOGLE_DOCS.CLIENT_KEY`	`string`	Google OAuth client ID for the Zotero Google Docs integration.
`GOOGLE_DOCS_DEV_MODE`	`boolean`	When `true`, the Google Docs integration uses the beta Apps Script endpoint. Controlled by `ZOTERO_GOOGLE_DOCS_DEV_MODE` in `config.sh`. Default: `false`.

Environment Variables for Testing

build.sh checks several environment variables to determine which browser to target when running tests:

Variable	Effect
`TEST_CHROME=1`	Forces `BUILD_BROWSER_EXT=1`; runs the test suite in Chrome/Chromium.
`TEST_FX=1`	Forces `BUILD_BROWSER_EXT=1`; runs the test suite in Firefox.
`TEST_SAFARI=1`	Forces `BUILD_SAFARI=1`; runs the test suite in Safari.

When any test variable is set, the corresponding platform is built regardless of -p flags. When no test variable and no -p flag is provided, all platforms are built.

Manifest Permissions

Manifest V2 (`manifest.json`) — Firefox and legacy Chromium

{
  "manifest_version": 2,
  "minimum_chrome_version": "55",
  "permissions": [
    "http://*/*", "https://*/*",
    "tabs", "contextMenus", "cookies", "storage", "scripting",
    "webRequest", "webRequestBlocking", "webNavigation", "declarativeNetRequest"
  ],
  "optional_permissions": ["management", "clipboardWrite"],
  "applications": {
    "gecko": {
      "id": "zotero@chnm.gmu.edu",
      "strict_min_version": "58.0"
    }
  }
}

Manifest V3 (`manifest-v3.json`) — Chrome/Edge (MV3), minimum version 88

{
  "manifest_version": 3,
  "minimum_chrome_version": "88",
  "host_permissions": ["http://*/*", "https://*/*"],
  "permissions": [
    "tabs", "contextMenus", "cookies", "scripting", "offscreen",
    "webRequest", "declarativeNetRequest", "webNavigation", "storage"
  ],
  "optional_permissions": ["management", "clipboardWrite"]
}

Required Permissions

http://*/*, https://*/* — Host access for content script injection and XHR to the local connector server.tabs — Reading tab URLs and IDs, sending messages to tabs.contextMenus — Right-click context menu integration.cookies — Collecting cookies via browser.cookies.getAll for callMethodWithCookies.storage — browser.storage.local for preferences (10 MB limit).scripting — Dynamic content script injection (MV3 replacement for tabs.executeScript).webRequest — Intercepting requests for content-type handling and user-agent replacement.webRequestBlocking — Synchronous request blocking (MV2 only; MV3 uses declarativeNetRequest).webNavigation — Detecting page navigations for proxy detection and translator triggering.declarativeNetRequest — Style intercept rules for importable file type detection.offscreen (MV3 only) — Creating offscreen documents for translation sandboxes.

Optional Permissions

management — Requested on demand (within a user gesture) when submitting debug reports or error reports, to enumerate installed extensions for system info.clipboardWrite — Requested on demand for the “Copy to Clipboard” button in the debug report confirmation dialog.

In the MV3 manifest, broad host access (http://*/*, https://*/*) is declared under host_permissions rather than permissions, reflecting the MV3 split between API permissions and host access. webRequestBlocking is removed in MV3; blocking behavior is handled by declarativeNetRequest rules in styleInterceptRules.json.

Get Started

Architecture

Core Systems

Development

Reference

Zotero Connectors Build and Configuration Reference

build.sh Flags

gulpfile.js Options

config.sh Variables

ZOTERO_CONFIG Constants

Environment Variables for Testing

Manifest Permissions

Manifest V2 (`manifest.json`) — Firefox and legacy Chromium

Manifest V3 (`manifest-v3.json`) — Chrome/Edge (MV3), minimum version 88

Required Permissions

Optional Permissions

​build.sh Flags

​gulpfile.js Options

​config.sh Variables

​ZOTERO_CONFIG Constants

​Environment Variables for Testing

​Manifest Permissions

​Manifest V2 (manifest.json) — Firefox and legacy Chromium

​Manifest V3 (manifest-v3.json) — Chrome/Edge (MV3), minimum version 88

Required Permissions

Optional Permissions

build.sh Flags

gulpfile.js Options

config.sh Variables

ZOTERO_CONFIG Constants

Environment Variables for Testing

Manifest Permissions

Manifest V2 (`manifest.json`) — Firefox and legacy Chromium

Manifest V3 (`manifest-v3.json`) — Chrome/Edge (MV3), minimum version 88