Quick Start

Using in a Blank Project

WIP: Not Yet Implemented

# Using npm
npx zotero-plugin create

# Using pnpm
pnpm dlx zotero-plugin create

Using in an Existing Project

01. Install the Package

You can install zotero-plugin-scaffold using your preferred package manager:

# npm
npm install -D zotero-plugin-scaffold

# yarn
yarn add -D zotero-plugin-scaffold

# pnpm
pnpm add -D zotero-plugin-scaffold

02. Create a Configuration File

The configuration file should be placed at one of the following locations:

zotero-plugin.config.ts  # Also supported: *.js, *.mjs, *.cjs, *.ts

You can use the defineConfig helper to enable type hints. Optional properties will default to predefined values if not explicitly specified.

import { defineConfig } from "zotero-plugin-scaffold";

export default defineConfig({
  name: "the plugin name",
  id: "the plugin id",
  namespace: "the plugin namespace",
  build: {
    esbuildOptions: [
      {
        entryPoints: ["src/index.ts"],
        bundle: true,
        target: "firefox115",
      },
    ],
  },
});

For a full list of configuration options, refer to the type definitions.

03. Create an Environment File

Define Zotero’s runtime configuration (e.g., binary paths, profile paths, and environment variables) in a .env file.

WARNING

Do not commit this file to your repository!

.env

# Path to the Zotero binary file.
# For macOS, the path is typically `*/Zotero.app/Contents/MacOS/zotero`.
ZOTERO_PLUGIN_ZOTERO_BIN_PATH=/path/to/zotero.exe

# Path to the profile used for development.
# To create a profile for development, start the profile manager with `/path/to/zotero.exe -p`.
# More info: https://www.zotero.org/support/kb/profile_directory
ZOTERO_PLUGIN_PROFILE_PATH=/path/to/profile

04. Add Scripts to package.json

Add the following scripts for development:

{
  "scripts": {
    "start": "zotero-plugin serve",
    "build": "zotero-plugin build",
    "release": "zotero-plugin release"
  }
}

05. Run the Plugin

Use the following commands to start development or build the plugin:

# Start the development server
pnpm run start

# Build the plugin
pnpm run build

Using in Node.js Code

You can also use zotero-plugin-scaffold programmatically in your Node.js scripts:

import { Build, Config } from "zotero-plugin-scaffold";

const config = await Config.loadConfig();

const builder = new Build(config);
await builder.run();