Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pixelsmith
✓ const Pixelsmith = require('pixelsmith')
✗ import Pixelsmith from 'pixelsmith'
The primary usage pattern for Pixelsmith, as documented and exemplified, is CommonJS. Using `require` directly provides the constructor function.
Pixelsmith (ESM)
✓ import Pixelsmith from 'pixelsmith'
✗ const Pixelsmith = require('pixelsmith')
While primarily a CJS library, Pixelsmith can be imported as a default export in ES Module contexts. Ensure your project's `package.json` `type` field is 'module' or use `.mjs` file extensions.
Canvas Methods (addImage, export)
✓ canvas.addImage(img, x, y);
canvas.export({ format: 'png' });
✗ import { addImage, export } from 'pixelsmith'
Methods like `addImage` and `export` are instance methods of the canvas object created by `pixelsmith.createCanvas()`, not top-level exports from the package.
Demonstrates how to initialize Pixelsmith, load dummy image file paths, create a canvas of a specific size, place the loaded images onto the canvas at given coordinates, and then export the resulting composite image as a PNG stream to a file.
const Pixelsmith = require('pixelsmith');
const fs = require('fs');
const path = require('path');
// Create dummy image files for demonstration
const createDummyImage = (filename, width, height) => {
// In a real scenario, these would be actual image files
// For this example, we'll just create placeholder files.
// Pixelsmith will attempt to read these, but without actual image data,
// it might fail. For a true runnable example, these would need to be valid images.
fs.writeFileSync(path.join(__dirname, filename), Buffer.from('dummy image data'));
};
// Ensure dummy images exist for the example to reference
createDummyImage('img1.jpg', 50, 100);
createDummyImage('img2.png', 75, 120);
// Create a new engine
const pixelsmith = new Pixelsmith();
// Interpret some images from disk
pixelsmith.createImages([path.join(__dirname, 'img1.jpg'), path.join(__dirname, 'img2.png')], function handleImages (err, imgs) {
// If there was an error, throw it
if (err) {
// In a real scenario, this error might indicate malformed images or missing files
console.error('Error creating images:', err);
return;
}
// We receive images in the same order they were given
// imgs[0].width; // 50 (pixels) - these properties are available after successful loading
// imgs[0].height; // 100 (pixels)
// Create a canvas that fits our images (200px wide, 300px tall)
const canvas = pixelsmith.createCanvas(200, 300);
// Add the images to our canvas (at x=0, y=0 and x=50, y=100 respectively)
// In a real scenario, 'imgs[0]' and 'imgs[1]' would be objects with pixel data.
// This example assumes they were loaded correctly for the purpose of demonstrating the API.
// For a fully functional example without actual images, mock these objects.
const mockImg1 = { width: 50, height: 100, /* ... other pixel data properties */ };
const mockImg2 = { width: 75, height: 120, /* ... other pixel data properties */ };
canvas.addImage(mockImg1, 0, 0);
canvas.addImage(mockImg2, 50, 100);
// Export canvas to image
const resultStream = canvas['export']({format: 'png'});
const outputFilePath = path.join(__dirname, 'output.png');
resultStream.pipe(fs.createWriteStream(outputFilePath))
.on('finish', () => console.log(`Sprite sheet saved to ${outputFilePath}`))
.on('error', (exportErr) => console.error('Error exporting canvas:', exportErr));
});
Errors
Common errors & fixes
Error: EMFILE: too many open files
The operating system's file descriptor limit has been reached due to Pixelsmith attempting to open too many image files concurrently.
fixSet the `concurrentFileLimit` option when instantiating Pixelsmith: `const pixelsmith = new Pixelsmith({ concurrentFileLimit: 20 });` TypeError: Pixelsmith is not a constructor
This usually occurs when using an ES module `import` statement in a CommonJS context, or vice-versa, leading to the constructor not being correctly resolved.
fixFor CommonJS, use `const Pixelsmith = require('pixelsmith');`. For ESM, ensure your `package.json` specifies `"type": "module"` and use `import Pixelsmith from 'pixelsmith';`. Error: Cannot find module 'get-pixels'
A dependency required by Pixelsmith (or one of its sub-dependencies) is missing from your `node_modules`.
fixRun `npm install` or `yarn install` again to ensure all dependencies are correctly installed. Clear your `node_modules` and package-lock file if the issue persists.
Error: unsupported pixel format
The underlying `get-pixels` library could not decode the provided image file, often due to a corrupted file or an unsupported image format being passed.
fixVerify that the input image files are valid and in a supported format (PNG, JPEG, GIF). Inspect the image files for corruption.
Audit
Dependencies
get-pixelsrequiredCore dependency for decoding various image formats (PNG, JPG, GIF) into pixel data.
save-pixelsrequiredCore dependency for encoding pixel data from the canvas into a final image format (e.g., PNG).