Creating a Mirador 4 Plugin

You can use Vite to quickly set up a new React project. Because Mirador is built with React, plugins need to be built using the same framework.

Vite is what we use in Mirador core to run development servers, testing, and to package the final library.

Setting up

npm create vite@latest

Select your options along these lines:

? Project name: › my-mirador-plugin
? Select a framework: › React
? Select a variant: › JavaScript
cd my-mirador-plugin
npm install

You can now run npm run dev and browse to the url provided by Vite.

From here you should edit Vite's default config to distribute in Library Mode. This will allow others to import your plugin as a packaged library. See the Mirador Download Plugin and Vite's documentation for reference.

Note: Vite is definitely not required, it is just a tool we find handy for setting up and building plugins. You can design your framework as desired. React is the only requirement.

As an example here is a simple build script that you could end-up with: Here is the basic setup for a Mirador plugin build config.

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import fs from 'fs/promises';
import pkg from './package.json';

/**
 * Vite configuration
 */
export default defineConfig({
  build: {
    lib: {
      entry: './src/index.js',
      fileName: (format) => (format === 'umd' ? 'plugin-name.min.js': 'plugin-name.es.js'),
      formats: ['umd', 'es'], // Provide umd and es module builds.
      name: 'YourPluginNames', // The name of the global for the umd build.
    },
    rollupOptions: {
      // Exclude the peer dependencies from your final bundle. These are the dependencies from mirrador.
      external: (id) => {
        const peers = Object.keys(pkg.peerDependencies);
        return peers.indexOf(id) > -1
          || peers.find((peer) => id.startsWith(`${peer}/`));
      },
    },
    // Enable source mapping for better debuging.
    sourcemap: true,
  },
  plugins: [react()],
  server: {
    open: 'demo/src/index.html', // Your file for demonstrating your plugin.
    port: 4444, // Port to use on localhost.
  },
})

Dependencies

Once you have a scaffolded React app, make sure the dependencies play well with Mirador 4.

• React version requirement of React 18+
• Material UI 5.

Here is an example of what your peer dependencies would look like:

  "peerDependencies": {
    "@mui/icons-material": "^7.0.0",
    "@mui/material": "^7.0.0",
    "@mui/system": "^7.0.0",
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0",
    "mirador": "^4.0.0"
  },

Vite build.

Plugin conventions

Three properties are required: name, target, and mode.

{
  name: 'Demo',
  target: 'WindowTopBarPluginMenu',
  mode: 'add',
}

You can also pass additional properties mapStateToProps and mapDispatchToProps which take a function as a value and work similarly to their counterparts in redux and Mirador.

Default exports

To enable robust functionality, packages may contain multiple plugins that act in concert together. We encourage plugin publishers to publish individual plugins in a package as exports. However, we also recommend publishing the default export as an array of the plugins that are used together. This way they can be more easily imported and used by Mirador users.

Translations (i18n)

Mirador Core re-exports the useTranslation hook from the react-i18next for downstream consumers (i.e. plugin developers).

If you use translation in your plugin, you need to import useTranslation from Mirador:

✅ import { useTranslation } from 'mirador'

❌ import { useTranslation } from 'react-il8next'

These hooks assume you have a functional component. If you still using class-based components from React, you can use the withTranslation HOC that we also export from Mirador 4 Core.

Add plugins

Add plugins are only supported for a predefined set of components:

• Window
• BackgroundPluginArea
• WindowTopBarPluginMenu
• WorkspaceControlPanelButtons
• WorkspaceMenu
• WorkspaceOptionsMenu