Connector Preferences: Settings and Configuration

Zotero Connectors store their configuration in the Zotero.Prefs namespace, a thin synchronous cache layer backed by browser.storage.local (in BrowserExt builds) or the equivalent Safari storage API. All preference keys and their defaults are defined in src/common/zotero.js and overridden per-browser in src/browserExt/prefs.js or src/safari/prefs.js. The preferences UI (src/common/preferences/preferences.jsx) and the raw config editor (src/common/preferences/config.jsx) are built with React and opened as a full browser tab.

The `Zotero.Prefs` API

Reading preferences

// Synchronous read — only safe in the background page or after loadNamespace()
const value = Zotero.Prefs.get('downloadAssociatedFiles');

// Async read — safe anywhere, including injected content scripts
const value = await Zotero.Prefs.getAsync('downloadAssociatedFiles');

// Read multiple preferences at once (async)
const { downloadAssociatedFiles, automaticSnapshots } =
  await Zotero.Prefs.getAsync(['downloadAssociatedFiles', 'automaticSnapshots']);

Zotero.Prefs.get() in an injected script (content script) will throw if the preference has not been pre-loaded via loadNamespace(). Always use getAsync() in injected code, or ensure the namespace has been loaded first.

Writing and clearing preferences

// Write a single preference
Zotero.Prefs.set('downloadAssociatedFiles', false);

// Reset a preference to its default value
Zotero.Prefs.clear('downloadAssociatedFiles');

// Reset multiple preferences
Zotero.Prefs.clear(['downloadAssociatedFiles', 'automaticSnapshots']);

In the BrowserExt implementation (src/browserExt/prefs.js), set() and clear() are async and write through to browser.storage.local. The in-memory syncStorage object is updated immediately so subsequent synchronous get() calls reflect the new value.

browser.storage.local has a 10 MB limit per Chrome’s documentation. The connector approaches this limit when caching many translator source files. If a set() call fails due to quota exhaustion, the BrowserExt prefs.js automatically evicts five randomly chosen cached translator code entries and retries.

Inspecting all preferences

// Returns a Promise resolving to an object of all preference keys and current values.
// Excludes translatorMetadata and cached translator code.
const prefs = await Zotero.Prefs.getAll();

// Returns a plain object of all default values (synchronous)
const defaults = Zotero.Prefs.getDefault();

Pre-loading namespaces in injected scripts

Because injected scripts cannot access browser.storage directly, they must ask the background page to relay preferences. loadNamespace() fetches all preferences whose keys start with the given prefix and populates syncStorage so they can be read synchronously afterwards:

// Load all proxy-related preferences
await Zotero.Prefs.loadNamespace('proxies');

// Load multiple namespaces at once
await Zotero.Prefs.loadNamespace([
  'translators.',
  'downloadAssociatedFiles',
  'automaticSnapshots',
  'reportTranslationFailure',
  'capitalizeTitles'
]);

loadNamespace() throws if called from a background page. All preferences are always available synchronously in the background via the in-memory cache.

Clearing cached translator code

// Remove all cached translator source code from storage
await Zotero.Prefs.removeAllCachedTranslators();

This is exposed in the Preferences → Advanced pane as the Reset Translators button, which calls removeAllCachedTranslators() and then forces a fresh fetch from the repository.

The Preferences UI

The preferences window is defined in src/common/preferences/preferences.html and src/common/preferences/preferences.jsx. It is registered as the extension’s options page:

"options_ui": {
  "page": "preferences/preferences.html",
  "open_in_tab": true
}

Open it programmatically from any extension context with:

Zotero.Connector_Browser.openPreferences();

Panes

The preferences window has three panes:

General

Zotero client connection status, zotero.org authorization, and (in BrowserExt) the Import BibTeX/RIS/Refer files MIME-type handler setting.

Advanced

Debug logging, translator cache reset, error reporting, keyboard shortcuts, Google Docs integration, and the Open Translator Tester button (debug builds only).

Proxies

Proxy redirection settings and the configured proxy list. BrowserExt only — this pane is hidden in Safari builds.

The active pane is controlled by the URL fragment: preferences.html#proxies opens the Proxies pane directly. Preference checkboxes that carry a data-pref attribute are wired up automatically:

checkbox.checked = await Zotero.Prefs.getAsync(checkbox.dataset.pref);
checkbox.addEventListener('change', (event) => {
  Zotero.Prefs.set(event.target.dataset.pref, event.target.checked);
});

The Config Editor

The config editor (src/common/preferences/config.html + config.jsx) shows every raw preference key and its current value in a filterable table. It is intended for power users and developers. Access it from Preferences → Advanced → Config Editor. A confirmation dialog warns that changing settings can harm stability and security before the editor opens. In the editor you can:

Filter preferences by key name
Double-click a row to edit its value (booleans toggle automatically; other types prompt for a new JSON-encoded value)
Reset any preference to its default with the Reset link
Add a new preference key/value pair with Add Preference

The table is rendered by Zotero_Preferences_Config.Table (React) and calls Zotero.Prefs.getAll() on load to populate itself.

Preference Reference

All defaults are defined in the DEFAULTS object inside Zotero.Prefs (src/common/zotero.js).

General preferences

Preference key	Default	Description
`downloadAssociatedFiles`	`true`	Automatically download PDFs and other attachments when saving items to Zotero
`automaticSnapshots`	`true`	Save a webpage snapshot when saving to zotero.org (saves to the Zotero client are controlled by a separate client-side preference)
`interceptKnownFileTypes`	`true`	Intercept browser downloads of PDF, BibTeX, RIS, and Refer files and import them into Zotero (BrowserExt only, requires Zotero to be running)
`allowedInterceptHosts`	`[]`	List of hostnames for which file-type interception is enabled
`allowedCSLExtensionHosts`	`[...]`	Array of URL-prefix regexp strings for allowed CSL extension hosts (e.g. raw.githubusercontent.com)
`capitalizeTitles`	`false`	Apply title-case capitalisation to imported item titles
`reportTranslationFailure`	`true`	Automatically send a report when a translator throws an error
`firstUse`	`true`	Whether to show the first-use welcome dialog
`firstSaveToServer`	`true`	Whether to show the first-save-to-server prompt
`lastVersion`	`""`	The last connector version that ran; used for migration logic
`connector.url`	`http://127.0.0.1:23119/`	Base URL of the Zotero connector HTTP server running inside the Zotero client

Translator cache preferences

Preference key	Default	Description
`translatorMetadata`	`[]`	Cached array of translator metadata objects (GUID, label, target regexp, etc.)
`connector.repo.lastCheck.localTime`	`0`	Unix timestamp (local) of the last translator repository check
`connector.repo.lastCheck.repoTime`	`0`	Unix timestamp (repo) of the last translator repository check

Proxy preferences

All proxy settings live under the proxies. namespace and are available after Zotero.Prefs.loadNamespace('proxies').

Preference key	Default	Description
`proxies.transparent`	`true`	Enable transparent proxy redirection
`proxies.autoRecognize`	`true`	Automatically detect and prompt to save new proxies (BrowserExt only)
`proxies.showRedirectNotification`	`true`	Show a notification bar when a request is redirected through a proxy
`proxies.disableByDomain`	`false`	Disable proxy redirection when the current domain matches `disableByDomainString`
`proxies.disableByDomainString`	`'.edu'`	Domain suffix that disables proxy redirection
`proxies.proxies`	`[]`	Array of saved proxy configuration objects
`proxies.clientChecked`	`false`	Whether the Zotero client has been queried for its proxy list
`proxies.loopPreventionTimestamp`	`0`	Timestamp until which proxy redirection is suspended to break redirect loops

Debug preferences

Preference key	Default	Description
`debug.store`	`false`	Persist debug output to storage so it survives restarts
`debug.store.limit`	`750000`	Maximum number of characters to store in the debug buffer
`debug.level`	`5`	Debug verbosity level (1 = errors only, 5 = verbose)
`debug.stackTrace`	`false`	Include stack traces in debug output
`debug.time`	`false`	Prefix each debug line with a timestamp

Integration preferences

Preference key	Default	Description
`integration.googleDocs.enabled`	`true`	Enable the Zotero Google Docs integration
`integration.googleDocs.useV2API`	`false`	Use the Google Apps Script v2 API for Google Docs integration
`integration.googleDocs.forceDisableV2API`	`false`	Force-disable the v2 API even if `useV2API` is true
`shortcuts.cite`	`{ctrlKey: true, altKey: true, key: 'c'}`	Keyboard shortcut for cite-while-you-write (macOS default uses `metaKey + ctrlKey`)

Storage Backend

Chrome / Edge / Firefox (BrowserExt)
Safari

Preferences are stored in browser.storage.local. The BrowserExt prefs.js overrides Zotero.Prefs.init(), set(), and clear() to read and write through this API. init() loads the entire storage area into syncStorage at extension startup:

Zotero.Prefs.init = async function() {
  this.syncStorage = await browser.storage.local.get(null);
};

Subsequent get() calls are served from the in-memory syncStorage object without hitting storage again.

Safari uses its own src/safari/prefs.js implementation, which bridges to the Swift global page for storage access. The API surface is identical to the BrowserExt version.

Get Started

Architecture

Core Systems

Development

Reference

Connector Preferences: Settings and Configuration

The `Zotero.Prefs` API

Reading preferences

Writing and clearing preferences

Inspecting all preferences

Pre-loading namespaces in injected scripts

Clearing cached translator code

The Preferences UI

Panes

General

Advanced

Proxies

The Config Editor

Preference Reference

General preferences

Translator cache preferences

Proxy preferences

Debug preferences

Integration preferences

Storage Backend

​The Zotero.Prefs API

​Reading preferences

​Writing and clearing preferences

​Inspecting all preferences

​Pre-loading namespaces in injected scripts

​Clearing cached translator code

​The Preferences UI

​Panes

General

Advanced

Proxies

​The Config Editor

​Preference Reference

​General preferences

​Translator cache preferences

​Proxy preferences

​Debug preferences

​Integration preferences

​Storage Backend

The `Zotero.Prefs` API

Reading preferences

Writing and clearing preferences

Inspecting all preferences

Pre-loading namespaces in injected scripts

Clearing cached translator code

The Preferences UI

Panes

The Config Editor

Preference Reference

General preferences

Translator cache preferences

Proxy preferences

Debug preferences

Integration preferences

Storage Backend