|
| 1 | +# Contributing Plugins to SnapDOM |
| 2 | + |
| 3 | +## Quick Start |
| 4 | + |
| 5 | +```bash |
| 6 | +npx degit zumerlab/snapdom/packages/plugin-template snapdom-plugin-yourname |
| 7 | +cd snapdom-plugin-yourname |
| 8 | +npm install |
| 9 | +``` |
| 10 | + |
| 11 | +```js |
| 12 | +// index.js |
| 13 | +export function yourPlugin(options = {}) { |
| 14 | + return { |
| 15 | + name: 'your-plugin', |
| 16 | + afterClone(ctx) { |
| 17 | + // modify ctx.clone |
| 18 | + } |
| 19 | + }; |
| 20 | +} |
| 21 | +``` |
| 22 | + |
| 23 | +```js |
| 24 | +// test it |
| 25 | +import { snapdom } from '@zumer/snapdom'; |
| 26 | +import { yourPlugin } from './index.js'; |
| 27 | + |
| 28 | +const result = await snapdom(document.body, { |
| 29 | + plugins: [yourPlugin()] |
| 30 | +}); |
| 31 | +const img = await result.toPng(); |
| 32 | +``` |
| 33 | + |
| 34 | +```bash |
| 35 | +npm publish |
| 36 | +``` |
| 37 | + |
| 38 | +Then open a PR to list it in the [Plugin Directory](https://snapdom.dev/plugins). |
| 39 | + |
| 40 | +## How plugins are distributed |
| 41 | + |
| 42 | +**Official plugins** ship as `@zumer/snapdom-plugins`, a separate package that keeps the core lightweight. They live in `packages/plugins/` inside the snapdom monorepo. |
| 43 | + |
| 44 | +**Community plugins** go on npm as `snapdom-plugin-[name]`. Your repo, your rules. |
| 45 | + |
| 46 | +Both show up in the same plugin directory on the site. |
| 47 | + |
| 48 | +## Conventions |
| 49 | + |
| 50 | +**Naming:** |
| 51 | +- npm package: `snapdom-plugin-[name]` |
| 52 | +- Plugin `name` field: lowercase kebab-case (e.g., `'my-plugin'`) |
| 53 | +- Main export: camelCase factory function (e.g., `myPlugin`) |
| 54 | + |
| 55 | +**Structure:** |
| 56 | +- Always use the factory pattern (accept options, return plugin object) |
| 57 | +- Set sensible defaults for all options |
| 58 | +- Export as both named and default export |
| 59 | + |
| 60 | +**Hooks:** |
| 61 | +`beforeSnap` → `beforeClone` → `afterClone` → `beforeRender` → `afterRender` → `beforeExport` → `afterExport` + `defineExports` |
| 62 | + |
| 63 | +Full reference in [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). |
| 64 | + |
| 65 | +**Categories:** |
| 66 | +Tag yours with one of: `capture`, `transform`, `export`, `integration`, `utility` |
| 67 | + |
| 68 | +## Submitting to the Plugin Directory |
| 69 | + |
| 70 | +### Option A: Open a PR (recommended) |
| 71 | + |
| 72 | +Add one line to [`docs/community-plugins.md`](./docs/community-plugins.md). The table format is: |
| 73 | + |
| 74 | +``` |
| 75 | +| name | description | category | npm | github | author | |
| 76 | +``` |
| 77 | + |
| 78 | +Example: |
| 79 | + |
| 80 | +``` |
| 81 | +| snapdom-plugin-watermark | Add text or image watermarks to captures | transform | snapdom-plugin-watermark | https://github.com/you/snapdom-plugin-watermark | @you | |
| 82 | +``` |
| 83 | + |
| 84 | +The plugin directory page loads this file automatically — no HTML editing needed. |
| 85 | + |
| 86 | +### Option B: Open an Issue |
| 87 | + |
| 88 | +Provide: plugin name, npm link, GitHub link, category, one-line description. |
| 89 | + |
| 90 | +## Quality Guidelines |
| 91 | + |
| 92 | +1. Works with `snapdom@latest` and `snapdom@dev`. |
| 93 | +2. Zero side effects. Restore DOM mutations. |
| 94 | +3. Handles errors. Wrap risky code in `try/catch`. |
| 95 | +4. Has a README with install, usage, options, and an example. |
| 96 | +5. Lists `@zumer/snapdom` as a peerDependency. |
| 97 | +6. Minimal dependencies. Ideally zero. |
| 98 | +7. Includes `snapdom` and `snapdom-plugin` keywords in package.json. |
| 99 | + |
| 100 | +## Plugin Ideas |
| 101 | + |
| 102 | +Some things the community has asked for: |
| 103 | + |
| 104 | +- **Redact** blur or black-bar sensitive content by selector |
| 105 | +- **Watermark** text/image watermarks with positioning |
| 106 | +- **PDF Export** export captures as PDF |
| 107 | +- **Annotations** arrows, circles, and callouts |
| 108 | +- **Dark Mode** force dark/light theme on captures |
| 109 | +- **Crop** crop to a region within the capture |
| 110 | +- **Responsive** capture at multiple viewport sizes |
| 111 | +- **Diff** visual diff between two captures |
| 112 | +- **Upload** direct upload to S3, Cloudinary, Imgur |
| 113 | +- **QR Code** embed a QR code linking to the source URL |
| 114 | + |
| 115 | +## Getting Help |
| 116 | + |
| 117 | +- [Discussions](https://github.com/zumerlab/snapdom/discussions) for questions and ideas |
| 118 | +- [Plugin Spec](./PLUGIN_SPEC.md) for the full reference |
| 119 | +- [Issues](https://github.com/zumerlab/snapdom/issues) for bugs and feature requests |
0 commit comments