Getting Started
Learn how to install and use the images-watermark package in your Node.js projects.
Requirements
Before you begin, make sure your environment meets these requirements.
- Node.js 20.0.0 or higher
- npm 10.0.0 or higher
- Support for async/await
- Access to file system for reading/writing images
Installation
Install the images-watermark package using your preferred package manager:
Terminal
1# Using npm
2npm install images-watermark
3
4# Using yarn
5yarn add images-watermark
6
7# Using pnpm
8pnpm add images-watermarkQuick Start
Here's a simple example to get you started with adding watermarks to your images:
Make sure the input image files exist and you have write permissions for the output directory.
app.js
1const { singleImageWatermark } = require('images-watermark');
2const path = require('path');
3
4const watermarkSingleImage = async function (req, res) {
5 try {
6 const watermarkedImage = await singleImageWatermark({
7 // Path to the image you want to watermark
8 imagePath: path.join(__dirname, '../../../public/images/image.jpg'),
9
10 // Path to the watermark image (e.g., logo or watermark text)
11 watermarkPath: path.join(__dirname, '../../../public/images/Watermark.png'),
12
13 // Allowed referrers for cross-origin resource sharing (CORS)
14 allowedReferrers: ['http://localhost:3000'],
15
16 // Custom headers to mimic the request context
17 headers: {
18 host: 'localhost:3000',
19 connection: 'keep-alive',
20 'user-agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
21 },
22 });
23
24 // Set the response content type and send the watermarked image
25 res.setHeader('Content-Type', 'image/png');
26 return res.send(watermarkedImage);
27 } catch (error) {
28 console.error('Error generating watermarked image:', error);
29 res.status(500).send('An error occurred while processing the image.');
30 }
31};Watermarking Multiple Images
Process multiple images at once using the multiImageWatermark function:
batch-watermark.js
1const { multiImageWatermark } = require('images-watermark');
2const path = require('path');
3
4const watermarkMultipleImages = async function (req, res) {
5 try {
6 const watermarkedImages = await multiImageWatermark({
7 // Path to the images you want to watermark
8 imagePaths: [
9 path.join(__dirname, '../../../public/images/image1.jpg'),
10 path.join(__dirname, '../../../public/images/image2.jpg')
11 ],
12
13 // Path to the watermark image (e.g., logo or watermark text)
14 watermarkPath: path.join(__dirname, '../../../public/images/Watermark.png'),
15
16 // Allowed referrers for cross-origin resource sharing (CORS)
17 allowedReferrers: ['http://localhost:3000'],
18
19 // Custom headers to mimic the request context
20 headers: {
21 host: 'localhost:3000',
22 connection: 'keep-alive',
23 'user-agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
24 },
25 });
26
27 return res.send(watermarkedImages);
28 } catch (error) {
29 console.error('Error generating watermarked images:', error);
30 res.status(500).send('An error occurred while processing the images.');
31 }
32};Adding Text Watermarks
Add custom text watermarks with full styling control:
text-watermark.js
1const { singleImageWatermark } = require('images-watermark');
2const path = require('path');
3
4const addTextWatermark = async function (req, res) {
5 try {
6 const watermarkedImage = await singleImageWatermark({
7 imagePath: path.join(__dirname, '../../../public/images/image.jpg'),
8 allowedReferrers: ['http://localhost:3000'],
9 headers: {
10 host: 'localhost:3000',
11 connection: 'keep-alive',
12 'user-agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
13 },
14 // Text watermark options
15 textWatermark: 'My Watermark Text',
16 appName: 'My App',
17 textColor: '#ffffff',
18 opacity: '0.7',
19 fontWeight: '800',
20 textLineSpacing: 1.2,
21 fontFamily: 'Inter, Arial, sans-serif'
22 });
23
24 res.setHeader('Content-Type', 'image/png');
25 return res.send(watermarkedImage);
26 } catch (error) {
27 console.error('Error generating text watermarked image:', error);
28 res.status(500).send('An error occurred while processing the image.');
29 }
30};ES Modules Support
The package also supports ES module imports. Here's how to use it with modern JavaScript:
app.mjs
1import { singleImageWatermark } from 'images-watermark';
2import path from 'path';
3
4// ES Module syntax
5const watermarkedImage = await singleImageWatermark({
6 imagePath: path.join(process.cwd(), 'public/images/image.jpg'),
7 watermarkPath: path.join(process.cwd(), 'public/images/watermark.png'),
8 allowedReferrers: ['http://localhost:3000'],
9 headers: {
10 host: 'localhost:3000',
11 connection: 'keep-alive',
12 'user-agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
13 },
14});Basic Usage
The images-watermark package provides two main functions for adding watermarks:
Single Image Watermark
Add watermarks to individual images
singleImageWatermark()
- • Process one image at a time
- • Image or text watermarks
- • Referrer-based access control
- • Custom headers support
Multiple Images Watermark
Process multiple images in batch
multiImageWatermark()
- • Batch processing
- • Same watermark for all images
- • Efficient for large datasets
- • Consistent watermarking
Required Parameters
Both functions require these essential parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| imagePath | string | Yes | Path to the original image |
| imagePaths | array | Yes* | Array of image paths (multiImageWatermark only) |
| headers | object | Yes | Headers for API calls |
| allowedReferrers | array | Yes | List of allowed domains for CORS |
Next Steps
Now that you have the basics down, explore more advanced features: