Image Placeholder Generator

A simple Node.js package to generate base64-encoded image placeholders from an image file. Perfect for loading image placeholders in web applications.

Features

• Generate a base64-encoded placeholder image from an input image
• Supports multiple image formats (JPEG, PNG, WebP)
• Configurable placeholder dimensions and blur intensity
• Comprehensive error handling and input validation
• Easy to use as a CLI tool or library
• TypeScript support with full type definitions
• High test coverage with comprehensive test suite

Installation

To use the image-placeholder-generator in your project, you can install it via npm:

npm install image-placeholder-generator 

Usage

As a Library You can use this package programmatically in your Node.js application.

JavaScript

const { generatePlaceholder } = require('image-placeholder-generator');

// Generate a base64 placeholder from an image with default options
generatePlaceholder('./path/to/your/image.jpg')
  .then((placeholder) => {
    console.log('Generated base64 placeholder:', placeholder);
  })
  .catch((error) => {
    console.error('Error generating placeholder:', error);
  });

// Generate a placeholder with custom options
const options = {
  width: 20,
  height: 15,
  blur: 2,
  format: 'png'
};

generatePlaceholder('./path/to/your/image.jpg', options)
  .then((placeholder) => {
    console.log('Generated PNG placeholder:', placeholder);
  })
  .catch((error) => {
    console.error('Error generating placeholder:', error);
  });

TypeScript

import { generatePlaceholder, PlaceholderOptions } from 'image-placeholder-generator';

const options: PlaceholderOptions = {
  width: 20,
  height: 15,
  blur: 2,
  format: 'webp'
};

const placeholder = await generatePlaceholder('./path/to/your/image.jpg', options);

As a CLI Tool If you installed the package globally, you can use it from the command line.

1. Install the package globally:

npm install -g image-placeholder-generator

2. Run the CLI tool with various options:

# Basic usage
generate-placeholder ./path/to/your/image.jpg

# With custom dimensions and format
generate-placeholder ./path/to/your/image.jpg --width 20 --height 15 --format png

# Output as JSON with metadata
generate-placeholder ./path/to/your/image.jpg --format webp --output json

# Show help
generate-placeholder --help

This will output the base64-encoded placeholder string or JSON object.

Testing

To run the tests for this package, use Jest. First, make sure Jest is installed:

npm install --save-dev jest

Then, run the tests:

npm test

Contributing

We welcome contributions! If you'd like to improve the package, feel free to fork the repository and submit a pull request.

Steps for Contributing:

1. Fork this repository.
2. Clone your fork to your local machine.
3. Make your changes and test them.
4. Submit a pull request to the main repository.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

If you encounter any issues or have suggestions, feel free to open an issue.

Breakdown of the README Sections:

1. Title: Briefly describes the purpose of the package.
2. Features: A quick overview of what your package does.
3. Installation: Instructions for installing the package.
4. Usage: Example code for using the package both as a library and CLI tool.
5. Testing: Instructions for running tests with Jest.
6. Contributing: Basic guidelines for contributing to the project.
7. License: Licensing information.

Let me know if you want to customize it further!