Skip to content

Latest commit

 

History

History
155 lines (109 loc) · 4.9 KB

CONTRIBUTING_PLUGINS.md

File metadata and controls

155 lines (109 loc) · 4.9 KB

Contributing Plugins to SnapDOM

Plugins can transform captured state, add exports or connect captures to another service. This guide targets SnapDOM v3. See Installation for the published versions.

Quick Start

Install SnapDOM as a dev dependency:

npm install --save-dev @zumer/snapdom@latest

Scaffold a plugin from the template:

npx degit zumerlab/snapdom/packages/plugin-template snapdom-plugin-yourname
cd snapdom-plugin-yourname
npm install --save-dev @zumer/snapdom@latest

The template installation guide covers the same steps and the peer range to keep.

// index.js
export function yourPlugin(options = {}) {
  return {
    name: 'your-plugin',
    afterClone(ctx) {
      // modify ctx.clone
    }
  };
}
// test it
import { snapdom } from '@zumer/snapdom';
import { yourPlugin } from './index.js';

const result = await snapdom(document.body, {
  plugins: [yourPlugin()]
});
const img = await result.toPng();
npm publish

Then open a PR to list it in the Plugin Directory.

How plugins are distributed

The official toolbox ships as @zumer/snapdom-plugins from packages/plugins/ in this repository; PDF, Vector and Stream ship as @zumer/snapdom-pdf, @zumer/snapdom-vector and @zumer/snapdom-stream from packages/pdf/, packages/vector/ and packages/stream/.

Community plugins use the npm name snapdom-plugin-[name] and are maintained in their own repositories.

Both show up in the same plugin directory on the site.

Conventions

Naming:

  • npm package: snapdom-plugin-[name]
  • Plugin name field: lowercase kebab-case (e.g., 'my-plugin')
  • Main export: camelCase factory function (e.g., myPlugin)

Structure:

  • Always use the factory pattern (accept options, return plugin object)
  • Set sensible defaults for all options
  • Export a named factory function; the template also includes a default export

Hooks:

beforeSnap → beforeClone → resolveNode → afterClone → beforeRender → afterRender
→ defineExports → [beforeExport → exporter → afterExport] → afterSnap

resolveNode runs per source node. The bracketed segment runs per export; afterSnap runs once after the first successful export.

Full reference in PLUGIN_SPEC.md.

Categories:

Tag yours with one of: capture, transform, export, integration, utility

Submitting to the Plugin Directory

Option A: Open a PR (recommended)

Add one line to docs/community-plugins.md. The table format is:

| name | description | category | npm | github | author |

Example:

| snapdom-plugin-watermark | Add text or image watermarks to captures | transform | snapdom-plugin-watermark | https://github.com/you/snapdom-plugin-watermark | @you |

The plugin directory page loads this file automatically.

Option B: Open an Issue

Provide: plugin name, npm link, GitHub link, category, one-line description.

Make it discoverable

Add the snapdom-plugin GitHub topic to your repository under About → Topics. The topic directory complements the curated plugin list on the SnapDOM site.

Quality Guidelines

  1. Test against the SnapDOM versions you declare as supported, including v3.
  2. Restore any changes to the live DOM.
  3. Recover from errors where possible; otherwise report the failure instead of returning incomplete output.
  4. Write a README with installation, usage, options and an example.
  5. List @zumer/snapdom as a peerDependency.
  6. Keep dependencies minimal, ideally zero.
  7. Include snapdom and snapdom-plugin keywords in package.json.

Test in the browsers you support, including repeated captures and delayed exports from an older result. Mark capture hooks pure: true only when they are deterministic and idempotent; see fast paths.

Plugin Ideas

Check existing plugins before starting. Plugins can add workflows such as:

  • Redact blur or black-bar sensitive content by selector
  • Watermark text/image watermarks with positioning
  • PDF Export custom layouts or pagination beyond the official PDF plugin
  • Annotations arrows, circles, and callouts
  • Dark Mode force dark/light theme on captures
  • Crop region-selection tools around core's clip option
  • Responsive capture at multiple viewport sizes
  • Diff visual diff between two captures
  • Upload direct upload to S3, Cloudinary, Imgur
  • QR Code embed a QR code linking to the source URL

Getting Help