Plugins can transform captured state, add exports or connect captures to another service. This guide targets SnapDOM v3. See Installation for the published versions.
Install SnapDOM as a dev dependency:
npm install --save-dev @zumer/snapdom@latestScaffold 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@latestThe 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 publishThen open a PR to list it in the Plugin Directory.
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.
Naming:
- npm package:
snapdom-plugin-[name] - Plugin
namefield: 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
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.
Provide: plugin name, npm link, GitHub link, category, one-line description.
Add the snapdom-plugin GitHub topic to your
repository under About → Topics. The topic directory complements the curated plugin
list on the SnapDOM site.
- Test against the SnapDOM versions you declare as supported, including v3.
- Restore any changes to the live DOM.
- Recover from errors where possible; otherwise report the failure instead of returning incomplete output.
- Write a README with installation, usage, options and an example.
- List
@zumer/snapdomas a peerDependency. - Keep dependencies minimal, ideally zero.
- Include
snapdomandsnapdom-pluginkeywords 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.
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
clipoption - 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
- Discussions for questions and ideas
- Plugin Spec for the full reference
- Issues for bugs and feature requests