====== Building the Zotero Desktop App ======

**Note:** If you don't plan to make any code changes yourself, and only wish to run the latest prerelease versions of Zotero, you can just install a [[/support/beta_builds|beta build]].

===== Build Steps ====

//**Windows users:** The following commands assume a POSIX-compliant system. To build Zotero on Windows, please follow the [[building_the_desktop_app_windows_notes|Windows-specific steps]] first.//

  - Make sure you have Git and Git LFS installed. ''git lfs'' shouldn't show an error.
  - Clone the Zotero source code: <code sh>git clone --recursive https://github.com/zotero/zotero zotero-client</code>
  - Change to the source code repo: <code sh>cd zotero-client</code>
  - Check your system for the necessary tools and install any that are missing: <code sh>app/scripts/check_requirements</code>This script checks all requirements for the official Zotero distribution system. If you're only creating a custom build, you only need the build requirements listed at the top, not the distribution requirements.
  - Install Node.js modules using Node 18 or later: <code sh>npm i</code>
  - Build and run Zotero: <code sh>app/scripts/build_and_run -r</code>

The build will be placed in the ''app/staging/'' folder in unpackaged form.

To build Zotero for another platform, first prepare Zotero's JavaScript source by running ''npm run build'' (or keep it prepared automatically as you make changes with ''npm start'') and then run ''app/scripts/dir_build'' with the ''-p'' flag for the desired platform (e.g., ''app/scripts/dir_build -p w'' for Windows).

If running ''npm run build'' manually, you may need to set the environment variable ''%%NODE_OPTIONS=--openssl-legacy-provider%%'' to avoid an ''ERR_OSSL_EVP_UNSUPPORTED'' error.
===== Running Your Custom Build ====

After you've built the client, you can continue to run it from ''app/staging/'' or move the app directory to a location of your choosing and start it normally.

For development, you'll generally want to leave the app in the staging directory and use the ''build_and_run'' [[#helper_script|helper script]], but you can also call the launcher directly:

=== Mac ===

''app/staging/Zotero.app/Contents/MacOS/zotero''

=== Linux ===

''app/staging/Zotero_linux-x86_64/zotero''

=== Windows ===

''app/staging/Zotero_win-x64/zotero.exe''

==== Command-line Flags ====

In most cases, you'll want to use the [[#helper_script|helper script]] below instead of passing these flags directly to the launcher, but it's helpful to know the available options, which also work with release and beta builds:

  * ''-ZoteroDebugText'' or ''-ZoteroDebug'' enable [[:debug_output#logging_to_a_terminal_window|real-time debug output]] from ''Zotero.debug()''
  * ''-jsconsole'' will open the Error Console (Tools → Developer → Error Console)
  * ''-jsdebugger'' starts the Firefox Browser Toolbox for [[developer_tools|debugging]], if Zotero was built with devtools enabled; not available in release builds
  * ''-ZoteroSkipBundledFiles'' skips style and translator initialization, which speeds up startup time after rebuilding if you're working on something that doesn't require styles or translators

==== Helper Script ====

For local development, you'll want to use the [[https://raw.githubusercontent.com/zotero/zotero/master/app/scripts/build_and_run|build_and_run]] helper script, which automates rebuilding Zotero and starting it with debug output enabled and the error console open. Create an alias for ''app/scripts/build_and_run'' with an appropriate name (e.g., ''zotero-source''), or create a shell script in your path that selects a preexisting development [[:kb/multiple_profiles|profile]] and forwards command-line parameters:

<code sh>
#!/bin/bash -e
export ZOTERO_PROFILE="Dev"
~/zotero-client/app/scripts/build_and_run "$@"
</code>

You can then run, e.g., ''zotero-source -r'' to rebuild Zotero with your changes and start it up.

Options:

  * ''-r''  Rebuild (calling `npm run build` automatically if `npm start` isn't running)
  * ''-d''  Include Firefox Developer Tools in a rebuild and open the Browser Toolbox
  * ''-b''  Skip bundled styles and translators — avoids extra work at startup if not needed
===== Running Zotero Plugins =====

See [[plugin_development#setting_up_a_plugin_development_environment|Setting Up a Plugin Development Environment]].

===== Packaging =====

==== Mac ====

  * In Keychain Access, create ''build'' keychain with password
  * Import Developer ID certificate, public key, and private key
  * Set up app-specific password for Apple developer account
  * Create a ''config-custom.sh'' file in ''app/'': <code sh>
SIGN=1
KEYCHAIN=build
KEYCHAIN_PASSWORD=<keychain password>
NOTARIZATION_BUNDLE_ID=<bundle id (e.g., org.foo.App) — only used for notification emails>
NOTARIZATION_USER="<username of Apple developer account>"
NOTARIZATION_PASSWORD="<app-specific password for Apple developer account>"
BUILD_PLATFORMS=m
</code>

==== Windows ====

  * Verify that git is set to check out files without modifying line endings.<code>
$ git config --global core.autocrlf

</code>The response should be either empty (meaning ''false'') or ''input''. If set to ''true'' (as it may be if you selected the default option while installing the Windows version of git), change this with the following command:<code>
git config --global core.autocrlf false
</code>See the [[http://git-scm.com/docs/git-config|git manual]] for details on this setting.
  * [[https://nsis.sourceforge.io/Download|Install NSIS 3]] and install the necessary plugins by running ''app/win/download-nsis-plugins''.
  * The [[https://developer.microsoft.com/en-US/windows/downloads/windows-sdk/|Windows SDK]] is needed for the included ''signtool.exe'' utility. You can uncheck all other installation options. Adjust the path in ''app/config.sh'' to point to the correct version of the Windows SDK.

===== Installation and Packaging Notes =====

**Note:** These instructions are not applicable on macOS, which handles protocol handler and MIME type registration through the bundled Info.plist file. Additionally, they are only applicable on Windows if for some reason you want to run Zotero without running the installer.

=== Protocol handler registration ===

Zotero should be registered as the system's default protocol handler for the ''zotero:%%//%%'' protocol.

=== File extensions and MIME types ===
Zotero should be registered as a handler for the following file extensions and MIME types:
^ File type description ^ File extension(s) ^ MIME type(s) ^
| Research Information Systems Document | ris | application/x-research-info-systems\\ application/x-endnote-refer\\ text/x-research-info-systems\\  text/application/x-research-info-systems \\ text/ris\\  ris |
| ISI Common Export Format Document | ciw, isi | application/x-inst-for-Scientific-info |
| Metadata Object Description Schema Document | mods | application/mods+xml |
| Resource Description Framework Document | rdf | application/rdf+xml |
| BibTeX Document | bib, bibtex | application/x-bibtex\\ text/x-bibtex |
| MARC Record | mrc, marc | application/marc |
| CSL Citation Style | csl | vnd.citationstyles.style+xml |


===== Distribution =====

Distribution steps are beyond the scope of this page, but see ''app/scripts/build_and_deploy'' for an example of the necessary steps.