SnapDOM

To build the project from the development branch, use the following commands. This will generate build outputs in the dist/ directory, including snapdom.js, snapdom.mjs, preCache.mjs, and plugins.mjs.

git clone https://github.com/zumerlab/snapdom.git
cd snapdom
git checkout dev
npm install
npm run compile

SnapDOM inlines images and background layers to ensure they are self-contained in the export.

• Inlining: Resolves src, currentSrc, and url() layers in background-image, mask, and border-image. Supports background-clip: text.
• Lazy Loading: Automatically resolves <picture> sources and common lazy attributes (e.g., data-src, data-lazy-src).
• CORS & Proxies: Uses a non-throwing fetch layer. You can configure a proxy using the useProxy option with templates like {url}, {urlRaw}, or ?url= suffix.
• Compression: The compress option (default true) performs perceptual downsampling to the visible resolution to keep file sizes small.
• Fallbacks: If an image fails, SnapDOM uses a fallbackURL (string or callback), then a placeholder box, then a hidden spacer.

A SnapDOM plugin is a JavaScript object with a unique name and lifecycle hooks. It is highly recommended to use the Plugin Factory Pattern, which wraps the plugin in a function to allow for configuration via an options object.

You can register plugins either per-capture (passed to the snapdom function) or globally (using snapdom.plugins()).

import { snapdom } from '@zumer/snapdom';
import { myPlugin } from 'snapdom-plugin-my-plugin';

// Per-capture registration with options
const result = await snapdom(element, {
  plugins: [myPlugin({ color: 'blue' })]
});

// Global registration
snapdom.plugins(myPlugin());

Official plugins are distributed as a separate package to keep the core library lightweight. You can install the entire suite or import individual tree-shakeable plugins.

Install command:

npm i @zumer/snapdom-plugins

To publish a community plugin to npm, follow these requirements:

1. Package Name: Must follow the convention snapdom-plugin-[name].
2. Plugin name field: Must be lowercase kebab-case (e.g., 'watermark').
3. Peer Dependency: Include @zumer/snapdom as a peer dependency.

Example package.json structure:

{
  "name": "snapdom-plugin-yourname",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "exports": { ".": "./index.js" },
  "peerDependencies": { "@zumer/snapdom": ">=0.9.0" }
}

Use the following shell commands to verify that the Chinese documentation (README_CN.md and FEATURES_CN.md) maintains structural alignment with the English source by checking heading, code fence, and table row counts.

for file in README.md README_CN.md FEATURES.md FEATURES_CN.md; do
  awk '
    /^#{1,6} / { headings++ }
    /^```/ { fences++ }
    /^\|/ { table_rows++ }
    END {
      printf "%s: headings=%d fences=%d table_rows=%d\n",
        FILENAME, headings, fences, table_rows
    }
  ' "$file"
done

To capture a single DOM element and export it directly to a PNG image in one line, use the snapdom.toPng() shortcut method.

import { snapdom } from '@zumer/snapdom';

const img = await snapdom.toPng(document.querySelector('#card'));
document.body.appendChild(img);

To build the project from the development branch, follow these steps:

git clone https://github.com/zumerlab/snapdom.git
cd snapdom
git checkout dev
npm install
npm run compile

To use plugins, import them and pass them into the plugins array within the options object of the snapdom function call. It is recommended to import plugins individually from their specific subpaths to support tree-shaking.

import { snapdom } from '@zumer/snapdom';
import { filter } from '@zumer/snapdom-plugins/filter';
import { timestampOverlay } from '@zumer/snapdom-plugins/timestamp-overlay';

const result = await snapdom(element, {
  plugins: [filter({ preset: 'grayscale' }), timestampOverlay()]
});
const png = await result.toPng();