Step-by-Step Guide to building a custom bulk image watermarker block for Gutenberg using custom WebAssembly modules
Leveraging WebAssembly for High-Performance Image Watermarking in Gutenberg
For e-commerce platforms, protecting intellectual property through watermarking is paramount. Traditional server-side image manipulation can become a bottleneck under heavy load. This guide details the construction of a custom Gutenberg block that offloads image watermarking to the client-side using WebAssembly (Wasm), offering a significant performance boost and reduced server strain. We’ll cover the Wasm module development, its integration into a React-based Gutenberg block, and the necessary PHP for plugin registration.
I. Developing the WebAssembly Image Processing Module
We’ll use C++ for our Wasm module, leveraging the Emscripten SDK to compile it. The core functionality will involve loading an image, applying a watermark (text or another image), and returning the processed image data. For simplicity, this example focuses on text watermarking. For image watermarking, a more complex library like libpng or libjpeg would be integrated.
A. C++ Source Code (watermarker.cpp)
This C++ code defines a function `apply_watermark` that takes image data (as a byte array), dimensions, and watermark text, then returns the modified image data. For a real-world scenario, you’d likely use a library to handle image decoding/encoding (e.g., stb_image, libpng, libjpeg) and drawing text (e.g., FreeType). For this demonstration, we’ll simulate basic pixel manipulation.
Note: This is a highly simplified example. A production-ready solution would require robust image format handling and text rendering.
#include <emscripten.h>
#include <vector>
#include <string>
#include <algorithm>
// Define a simple RGBA pixel structure
struct Pixel {
unsigned char r, g, b, a;
};
// Function to apply a text watermark.
// In a real scenario, this would involve image decoding, text rendering, and encoding.
// For this example, we'll just overlay some pixels to simulate watermarking.
extern "C" {
EMSCRIPTEN_KEEPALIVE
unsigned char* apply_watermark(unsigned char* image_data, int width, int height, const char* watermark_text, int text_len) {
// Allocate memory for the new image data. In a real app, you'd copy the original.
// For simplicity, we'll modify in-place or assume caller manages memory.
// A more robust approach would return a new buffer.
// Let's assume image_data is a RGBA buffer.
int num_pixels = width * height;
Pixel* pixels = reinterpret_cast<Pixel*>(image_data);
// Basic text overlay simulation: change a few pixels based on watermark text length.
// This is NOT actual text rendering.
int watermark_intensity = std::min(255, text_len * 10); // Arbitrary intensity
for (int i = 0; i < num_pixels; ++i) {
if (i % 100 < watermark_intensity / 10) { // Apply to some pixels
pixels[i].r = std::min(255, pixels[i].r + watermark_intensity / 4);
pixels[i].g = std::min(255, pixels[i].g + watermark_intensity / 4);
pixels[i].b = std::min(255, pixels[i].b + watermark_intensity / 4);
pixels[i].a = std::min(255, pixels[i].a + watermark_intensity / 4);
}
}
// In a real scenario, you'd return a pointer to newly allocated, encoded image data.
// For this example, we're modifying the input buffer.
// The caller is responsible for managing the memory of image_data.
return image_data;
}
// A function to free memory allocated by Wasm (if needed)
EMSCRIPTEN_KEEPALIVE
void free_memory(void* ptr) {
free(ptr);
}
}
B. Compiling to WebAssembly with Emscripten
Ensure you have Emscripten SDK installed. Navigate to your C++ source file directory and run the following command:
emcc watermarker.cpp -o watermarker.wasm -O3 -s WASM=1 -s EXPORTED_FUNCTIONS='["_apply_watermark", "_free_memory"]' -s MODULARIZE=1 -s ALLOW_MEMORY_GROWTH=1 -s SINGLE_FILE=1
Explanation of flags:
-o watermarker.wasm: Specifies the output file name.-O3: Enables aggressive optimizations.-s WASM=1: Ensures WebAssembly output.-s EXPORTED_FUNCTIONS='["_apply_watermark", "_free_memory"]': Makes specific C++ functions callable from JavaScript.-s MODULARIZE=1: Wraps the Wasm module in a JavaScript function, making it easier to load asynchronously.-s ALLOW_MEMORY_GROWTH=1: Allows the Wasm module’s memory to expand as needed.-s SINGLE_FILE=1: Bundles the Wasm binary and JS glue code into a single `.js` file (which will contain the Wasm as a data URI). This simplifies deployment for this example.
This command will generate a watermarker.js file. This file contains the JavaScript glue code and the Wasm module itself embedded as a data URI.
II. Building the Gutenberg Block (React & JavaScript)
We’ll create a custom Gutenberg block using React. The block will allow users to upload an image, input watermark text, and trigger the Wasm processing. The processed image will be displayed as a preview.
A. Plugin Structure
Set up a basic WordPress plugin structure:
wp-content/plugins/
└── custom-watermarker/
├── custom-watermarker.php
├── build/
│ ├── index.js
│ └── index.asset.php
├── src/
│ ├── index.js
│ ├── block.json
│ ├── editor.scss
│ ├── style.scss
│ └── components/
│ └── Watermarker.js
└── wasm/
└── watermarker.js <-- Generated by Emscripten
B. Plugin PHP (custom-watermarker.php)
This PHP file registers the block type and enqueues the necessary JavaScript and CSS assets.
<?php
/**
* Plugin Name: Custom Watermarker Block
* Description: Adds a Gutenberg block for client-side image watermarking using WebAssembly.
* Version: 1.0.0
* Author: Your Name
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly.
}
/**
* Registers the block using the metadata loaded from the `block.json` file.
* Behind the scenes, it registers also all assets so they can be enqueued
* through the block editor in the corresponding context.
*
* @see https://developer.wordpress.org/reference/functions/register_block_type/
*/
function custom_watermarker_block_init() {
register_block_type( __DIR__ . '/build', array(
'editor_script' => 'custom-watermarker-editor-script',
'editor_style' => 'custom-watermarker-editor-style',
'style' => 'custom-watermarker-style',
) );
}
add_action( 'init', 'custom_watermarker_block_init' );
/**
* Enqueue scripts and styles for the block editor.
*/
function custom_watermarker_enqueue_editor_assets() {
// Enqueue the WebAssembly module's JS wrapper.
// This assumes watermarker.js is placed in the 'wasm' directory.
// We'll enqueue it as a dependency for our main editor script.
wp_enqueue_script(
'custom-watermarker-wasm',
plugins_url( 'wasm/watermarker.js', __FILE__ ),
array(), // No dependencies for the Wasm loader itself
filemtime( plugin_dir_path( __FILE__ ) . 'wasm/watermarker.js' ),
true // Load in footer
);
// Enqueue the main editor script.
// Make sure 'custom-watermarker-wasm' is listed as a dependency.
wp_enqueue_script(
'custom-watermarker-editor-script',
plugins_url( 'build/index.js', __FILE__ ),
array( 'wp-blocks', 'wp-element', 'wp-editor', 'wp-components', 'wp-i18n', 'custom-watermarker-wasm' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/index.asset.php' ), // Use asset file for dependencies and version
true
);
// Enqueue editor-specific styles.
wp_enqueue_style(
'custom-watermarker-editor-style',
plugins_url( 'build/editor.css', __FILE__ ),
array( 'wp-edit-blocks' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/editor.css' )
);
// Enqueue front-end styles.
wp_enqueue_style(
'custom-watermarker-style',
plugins_url( 'build/style.css', __FILE__ ),
array(),
filemtime( plugin_dir_path( __FILE__ ) . 'build/style.css' )
);
}
add_action( 'enqueue_block_editor_assets', 'custom_watermarker_enqueue_editor_assets' );
// Note: The `register_block_type` function automatically handles asset registration
// based on `block.json`. The manual enqueuing above is for the Wasm module,
// which isn't directly managed by `block.json`'s asset definitions.
// Ensure `build/index.asset.php` is generated by your build process (e.g., @wordpress/scripts).
C. Block Configuration (src/block.json)
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "custom-watermarker/block",
"version": "0.1.0",
"title": "Image Watermarker",
"category": "media",
"icon": "format-image",
"description": "Apply a text watermark to images using WebAssembly.",
"keywords": [ "image", "watermark", "wasm", "ecommerce" ],
"attributes": {
"imageUrl": {
"type": "string"
},
"imageId": {
"type": "number"
},
"watermarkText": {
"type": "string",
"default": "© Your Brand"
},
"processedImageUrl": {
"type": "string"
}
},
"supports": {
"html": false
},
"textdomain": "custom-watermarker",
"editorScript": "file:./build/index.js",
"editorStyle": "file:./build/editor.css",
"style": "file:./build/style.css"
}
D. React Component for Block Editor (src/components/Watermarker.js)
This component handles the user interface in the Gutenberg editor, including image selection, text input, and interaction with the Wasm module.
import { __ } from '@wordpress/i18n';
import {
useBlockProps,
MediaUpload,
MediaUploadCheck,
RichText,
} from '@wordpress/block-editor';
import { Button, Spinner } from '@wordpress/components';
import { useState, useEffect, useRef } from '@wordpress/element';
import './editor.scss';
const Watermarker = ({ attributes, setAttributes }) => {
const { imageUrl, watermarkText, processedImageUrl } = attributes;
const blockProps = useBlockProps();
const [wasmModule, setWasmModule] = useState(null);
const [isLoadingWasm, setIsLoadingWasm] = useState(true);
const [isProcessing, setIsProcessing] = useState(false);
const originalImageRef = useRef(null); // To hold original image data for processing
// Load the WebAssembly module
useEffect(() => {
// Check if the Wasm module is already loaded (e.g., via wp_enqueue_script)
if (window.customWatermarkerWasm) {
setWasmModule(window.customWatermarkerWasm);
setIsLoadingWasm(false);
return;
}
// Fallback: Attempt to load if not globally available (less ideal for WP)
// This part might need adjustment based on how Emscripten's SINGLE_FILE works with WP enqueueing.
// The PHP enqueuing should make `customWatermarkerWasm` available globally.
console.warn('WebAssembly module not found globally. Ensure it is enqueued correctly.');
setIsLoadingWasm(false); // Prevent infinite loading if not found
}, []);
const onSelectImage = (media) => {
if (!media || !media.url) {
setAttributes({ imageUrl: undefined, imageId: undefined, processedImageUrl: undefined });
return;
}
setAttributes({ imageUrl: media.url, imageId: media.id, processedImageUrl: undefined });
// Fetch and store original image data for processing
fetch(media.url)
.then(response => response.blob())
.then(blob => blob.arrayBuffer())
.then(buffer => {
originalImageRef.current = new Uint8Array(buffer);
})
.catch(error => console.error('Error fetching image:', error));
};
const onUpdateWatermarkText = (newText) => {
setAttributes({ watermarkText: newText });
// Optionally re-process watermark on text change if an image is already loaded
if (imageUrl && originalImageRef.current) {
processWatermark();
}
};
const processWatermark = async () => {
if (!wasmModule || !originalImageRef.current || !imageUrl) {
console.error('Wasm module not ready or image data missing.');
return;
}
setIsProcessing(true);
try {
// --- Image Data Preparation ---
// This is a critical part. We need to get the image data in a format
// the Wasm module expects (e.g., RGBA byte array).
// For simplicity, we assume the fetched image is RGBA.
// A real implementation would use Canvas API to decode various formats (JPEG, PNG)
// into a consistent RGBA buffer.
// Example using Canvas API (more robust):
const img = new Image();
img.crossOrigin = "anonymous"; // Needed for CORS if image is external
img.onload = async () => {
const canvas = document.createElement('canvas');
canvas.width = img.width;
canvas.height = img.height;
const ctx = canvas.getContext('2d');
ctx.drawImage(img, 0, 0);
// Get RGBA data
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
const pixelData = imageData.data; // This is Uint8ClampedArray, compatible with Uint8Array
// --- Wasm Interaction ---
// Allocate memory in Wasm for image data
const imageBufferPtr = wasmModule._malloc(pixelData.length);
if (!imageBufferPtr) {
throw new Error('Failed to allocate memory in Wasm.');
}
// Copy image data to Wasm memory
const imageArray = new Uint8Array(wasmModule.memory.buffer, imageBufferPtr, pixelData.length);
imageArray.set(pixelData);
// Call the Wasm watermark function
const watermarkCStr = wasmModule.allocate(
new TextEncoder().encode(watermarkText + '\0'), 'i8', wasmModule.ALLOC_NORMAL
);
const processedDataPtr = wasmModule._apply_watermark(
imageBufferPtr,
canvas.width,
canvas.height,
watermarkCStr,
watermarkText.length
);
wasmModule._free(watermarkCStr); // Free watermark string memory
if (!processedDataPtr) {
throw new Error('WebAssembly watermark function failed.');
}
// Copy processed data back from Wasm memory
const processedPixelData = new Uint8Array(wasmModule.memory.buffer, processedDataPtr, pixelData.length);
// Create a new canvas to display the result
const resultCanvas = document.createElement('canvas');
resultCanvas.width = canvas.width;
resultCanvas.height = canvas.height;
const resultCtx = resultCanvas.getContext('2d');
const processedImageData = resultCtx.createImageData(canvas.width, canvas.height);
processedImageData.data.set(processedPixelData);
resultCtx.putImageData(processedImageData, 0, 0);
// Convert the result canvas to a data URL
const processedUrl = resultCanvas.toDataURL('image/png'); // Or image/jpeg
setAttributes({ processedImageUrl: processedUrl });
// Free memory allocated in Wasm
wasmModule._free(imageBufferPtr); // Free the original image data buffer
setIsProcessing(false);
};
img.onerror = (err) => {
console.error('Error loading image for processing:', err);
setIsProcessing(false);
};
img.src = imageUrl; // Set the source to trigger load
} catch (error) {
console.error('Watermarking failed:', error);
setIsProcessing(false);
}
};
return (
<div { ...blockProps }>
{!imageUrl && (
<MediaUploadCheck>
<MediaUpload
onSelect={ onSelectImage }
allowedTypes={ [ 'image' ] }
value={ attributes.imageId }
render={ ( { open } ) => (
<Button
variant="primary"
icon="upload"
onClick={ open }
>
{ __( 'Upload Image', 'custom-watermarker' ) }
</Button>
) }
/>
</MediaUploadCheck>
)}
{imageUrl && (
<div className="image-preview">
<img src={ processedImageUrl || imageUrl } alt="Preview" />
<div className="controls">
<RichText
tagName="p"
value={ watermarkText }
onChange={ onUpdateWatermarkText }
placeholder={ __( 'Enter watermark text...', 'custom-watermarker' ) }
className="watermark-text-input"
/>
{!processedImageUrl && (
<Button
isPrimary
onClick={ processWatermark }
disabled={ isLoadingWasm || isProcessing || !imageUrl }
className="watermark-button"
>
{ isProcessing ? <Spinner /> : __( 'Apply Watermark', 'custom-watermarker' ) }
</Button>
)}
<Button
variant="secondary"
onClick={ () => {
setAttributes({ imageUrl: undefined, imageId: undefined, processedImageUrl: undefined });
originalImageRef.current = null;
}}
className="remove-image-button"
>
{ __( 'Remove Image', 'custom-watermarker' ) }
</Button>
</div>
</div>
)}
</div>
);
};
export default Watermarker;
E. Main Block Entry Point (src/index.js)
This file registers the block with WordPress and points to the React component.
import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import Watermarker from './components/Watermarker';
import './editor.scss';
import './style.scss';
registerBlockType( metadata.name, {
edit: Watermarker,
save: () => null, // We'll handle saving the processed image URL via attributes
} );
F. Stylesheets (src/editor.scss, src/style.scss)
Basic styling for the block in the editor and on the front-end.
/* src/editor.scss */
.wp-block-custom-watermarker-block {
border: 1px dashed #ccc;
padding: 20px;
text-align: center;
.image-preview {
position: relative;
max-width: 100%;
margin-bottom: 15px;
img {
max-width: 100%;
height: auto;
display: block;
margin: 0 auto;
}
.controls {
margin-top: 15px;
display: flex;
flex-direction: column;
align-items: center;
gap: 10px;
.watermark-text-input {
width: 80%;
padding: 8px;
border: 1px solid #ddd;
border-radius: 4px;
}
.watermark-button,
.remove-image-button {
width: 80%;
}
}
}
.components-button {
margin-top: 10px;
}
}
/* src/style.scss */
.wp-block-custom-watermarker-block {
img {
max-width: 100%;
height: auto;
}
/* Add any front-end specific styles here */
}
G. Build Process
You’ll need Node.js and npm/yarn installed. Use `@wordpress/scripts` for an easy build setup.
1. Install dependencies:
cd wp-content/plugins/custom-watermarker npm init -y npm install @wordpress/scripts --save-dev
2. Add build scripts to your package.json:
{
"name": "custom-watermarker",
"version": "1.0.0",
"description": "Custom Watermarker Gutenberg Block",
"main": "build/index.js",
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
},
"keywords": ["wordpress", "gutenberg", "block"],
"author": "Your Name",
"license": "GPL-2.0-or-later",
"devDependencies": {
"@wordpress/scripts": "^27.0.0"
}
}
3. Run the build command:
npm run build
This will compile your React code, SCSS, and generate build/index.js, build/index.asset.php, build/editor.css, and build/style.css.
III. Handling Block Saving and Front-end Display
Since the `save` function in our block is set to `() => null`, the block itself won’t render anything on the front-end by default. The processed image URL is stored in the `processedImageUrl` attribute. To display the watermarked image on the front-end, we need to:
A. Save the Processed Image URL
The `processedImageUrl` attribute needs to be saved. Gutenberg’s `save` function is responsible for generating the static HTML markup. Since we’re using client-side processing, we can’t reliably generate the final HTML server-side. A common approach is to save the processedImageUrl as a custom attribute and then use a PHP filter or a dynamic block render callback to output the final <img> tag.
Modify src/index.js to include the save function:
import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import Watermarker from './components/Watermarker';
import './editor.scss';
import './style.scss';
registerBlockType( metadata.name, {
edit: Watermarker,
save: ( { attributes } ) => {
const { processedImageUrl, watermarkText } = attributes;
// If no processed image, save nothing or a placeholder.
// If processed, save an img tag with the URL and potentially watermark text as alt.
if ( ! processedImageUrl ) {
return null;
}
// Save the image and potentially the watermark text for accessibility.
// The watermark text itself isn't visually part of the saved HTML,
// but could be used for alt text or other metadata.
return (
<img
src={ processedImageUrl }
alt={ `Watermarked image: ${ watermarkText }` }
data-watermark-text={ watermarkText } // Store watermark text as data attribute if needed
className="custom-watermarked-image"
/>
);
},
} );
After running npm run build, this will generate HTML like <img src="data:image/png;base64,..." alt="Watermarked image: © Your Brand" data-watermark-text="© Your Brand" class="custom-watermarked-image" /> in your post content.
B. Handling Data URLs and Large Images
Saving the processed image as a Data URL directly in the post content can lead to very large HTML payloads, especially for high-resolution images. This can negatively impact page load times and database performance.
Recommended Alternatives:
- Server-Side Upload: After client-side processing, send the generated Data URL to a custom WordPress REST API endpoint. This endpoint would then save the image to the WordPress Media Library (like a regular upload) and return the URL of the saved media item. The block’s attribute would then be updated to store this media URL instead of the Data URL.
- Temporary Storage: Use browser’s `localStorage` or `sessionStorage` for the Data URL, and only display it if the block is loaded in the editor context. For the front-end, rely on a server-generated URL (e.g., from a media library upload).
- Optimize Data URL: Compress the PNG/JPEG before converting to Data URL.
For this example, we’ll stick with saving the Data URL directly for simplicity, but be mindful of the performance implications in production.
IV. Advanced Considerations and Enhancements
A. Image Watermark (Instead of Text)
To apply an image watermark:
- Modify the C++ code to accept watermark image data.
- Integrate an image loading/manipulation library (e.g., `stb_image`, `libpng`, `libjpeg`) into the Wasm module.
- In the JavaScript, load the watermark image using `Image` object and Canvas API, then pass its pixel data to Wasm.
B. Performance Optimization
Wasm Module:
- Profile the C++ code to identify bottlenecks.
- Use Emscripten’s optimization flags aggressively.
- Consider using libraries optimized for Wasm.
JavaScript/React:
- Debounce or throttle the `processWatermark` function if it’s called frequently (e.g., on text input change).
- Optimize image decoding/encoding using Canvas API.
- Avoid unnecessary re-renders in React.
- Implement lazy loading for images if many blocks are present.
C. Error Handling and User Feedback
Provide clear feedback to the user:
- Display loading indicators (spinners) during Wasm module loading and image processing.
- Show error messages if Wasm fails to load, memory allocation fails, or image processing encounters issues.
- Inform users about potential Data URL size limitations if applicable.
D. Security Considerations
While client-side processing reduces server load, ensure:
- The Wasm module is obtained from a trusted source.
- Input validation is performed (e.g., limiting watermark text length if necessary).
- If uploading processed images server-side, implement standard security checks for file uploads.
Conclusion
By integrating WebAssembly into a Gutenberg block, we’ve created a powerful, client-side image watermarking solution. This approach significantly enhances performance for e-commerce sites by reducing server dependency for image manipulation tasks. The step-by-step process outlined here provides a robust foundation for building advanced, performance-critical Gutenberg blocks.