@rtiodev/lightning-image
v1.0.1
Published
Get lightning fast information about images with little resources.
Downloads
15
Maintainers
Readme
Lightning Image ⚡️
An efficient and flexible image format detection and processing library. With Lightning Image
, you can effortlessly obtain the dimensions of images, determine their format, and even check if they are animated, all from just a few bytes of data!
Handling Large Images with Security and User Experience in Mind 🖼️🔍🔐
Lightning Image
is not just about handling large images; it's about doing it right. Some browsers have limitations with big pixel images, leading to not just processing issues but potential security vulnerabilities.
By relying on native methods, you may be forced to pass the image through the server for evaluation, opening the door to various risks. Lightning Image
addresses these concerns by fetching only the first 1000 bytes of the image data, validating the format, and obtaining dimensions even for immense images that other methods might struggle with.
Why it Matters?
- No Browser Limitations: Work seamlessly across browsers, without worrying about specific constraints on image size.
- Enhanced Security: Minimize the risk by handling image validation on the frontend, without the need for server-side evaluation.
- Improved User Experience: Provide instant feedback to users if an image cannot be loaded or uploaded, enhancing the overall user interaction.
- Efficient Processing: Handle large images with finesse, without bogging down the browser or compromising security.
- Perfect for Heavy Use Cases: Ideal for applications with extensive image processing needs where native methods might fail.
For Backend Solutions
If you're looking for a powerful image processing library specifically tailored for backend environments, you might want to explore Sharp, a high-performance Node.js image processing library. Lightning Image
is designed with browser environments in mind and offers unique solutions for front-end challenges.
With Lightning Image
, your image processing is not only lightning-fast but also secure and user-friendly. It's about making big feel small and safe! ⚡️🎨🛡️
Features
- 🌩️ Lightning-fast image detection and processing.
- 🔍 Detects various image formats including PNG, JPEG, GIF, WEBP, AVIF, BMP, and TIFF.
- 🔄 Dynamic format checker imports for optimized performance.
- 🖼️ Fetches only the first 1000 bytes to minimize bandwidth and speed up detection.
- 📦 Provides UMD build for broad compatibility.
Please note that currently the AVIF and TIFF image formats are behaving unexpectedly with some images. See the test file for details.
Installation
npm install lightning-image
Usage
JavaScript Module Import
import { getImageDimensions, getImageFormat, isAnimated } from 'lightning-image';
const imageURL = 'path_to_image/image.png';
// Get image dimensions
getImageDimensions(imageURL).then(dimensions => {
console.log(dimensions);
// { width: 100, height: 200, type: 'PNG' }
});
// Get image format
getImageFormat(imageURL).then(format => {
console.log(format); // e.g., 'PNG'
});
// Check if the image is animated
isAnimated(imageURL).then(animated => {
console.log(animated); // e.g., true
});
Using in HTML
If you'd like to include Lightning Image
directly in your HTML file, you can do so using the UMD build. Here's how:
- Include the script:
If hosting locally:
<script src="path_to_local_directory/lightning-image.js"></script>
Or, if using a CDN (this is just a placeholder link):
<script src="https://cdn.example.com/lightning-image/latest/lightning-image.js"></script>
- Use the library:
Once you've included the script, the library's functions will be available under a global namespace, e.g., LightningImage
:
<script>
const imageURL = 'path_to_image/image.png';
// Get image dimensions
LightningImage.getImageDimensions(imageURL).then(dimensions => {
console.log(dimensions); // { width: 100, height: 200, type: 'PNG' }
});
// Get image format
LightningImage.getImageFormat(imageURL).then(format => {
console.log(format); // e.g., 'PNG'
});
// Check if the image is animated
LightningImage.isAnimated(imageURL).then(animated => {
console.log(animated); // e.g., true
});
</script>
Build
The project provides various builds suitable for different environments getting leverage from UMD (Universal Module Definition).
Contribute
If you'd like to contribute to the development of Lightning Image, please follow these steps:
- Raise an Issue: Before making any changes, create an issue describing your idea or the desired change.
- Submit a PR: Once your idea is approved, create a Pull Request. Make sure to include or update unit tests.
- Testing & Code Style: Ensure all tests pass and fix any code style issues.
- Describe Your Changes: Clearly describe what you've changed and include testing instructions.
- Breaking Changes Alert: If your contribution introduces breaking changes, please highlight them. Any modification that disrupts the current workflow, like changing a namespace or functionality, is a breaking change.
Remember, if you're planning a significant refactor or introducing breaking changes, your PR might not be approved.
Once your PR is approved, it will be merged, and a new version will be released.
Certainly, let's add a development section to guide contributors through setting up the development environment and making changes.
Development
Setting Up the Development Environment
Clone the repository:
git clone https://github.com/yourusername/lightning-image.git cd lightning-image
Install dependencies:
Ensure you have Node.js and npm installed. Once you've cloned the project, install the required dependencies:
npm install
Understanding the project structure:
The main library logic is housed in
lightning.ts
, and specific format checkers for each image type are in their respective files, e.g.,png.ts
,jpeg.ts
, etc. Configuration for bundling is inwebpack.config.js
.
Making Changes
Branching:
Always create a new branch for your changes:
git checkout -b feature/my-new-feature
Code Style:
Please adhere to the existing coding style in the project. Proper naming, indentation, and comments are appreciated.
Testing:
If you introduce new features or changes, make sure they don't break existing functionality. If possible, add tests that cover your changes.
Building:
Before submitting your changes, build the project to ensure everything works:
npm run build
This will run the configurations specified in
webpack.config.js
and produce builds in thedist
directory.Committing Changes:
Keep your commit messages descriptive and concise. Group smaller changes into a single commit. This makes it easier to track changes and revert if needed:
git commit -m "Added a new feature to detect XYZ format"
Pushing and Creating a Pull Request:
Once you've committed your changes, push them to your branch:
git push origin feature/my-new-feature
Then, head to the GitHub repository and create a new Pull Request. Fill in the PR template with details about your change.
Feedback:
Maintainers will review your PR. Address any comments or feedback they might have. Once everything is approved, your changes will be merged.
Getting Help
If you run into issues or need guidance, feel free to open an issue or contact the maintainers.
License
This project is licensed under the GNU GENERAL PUBLIC LICENSE Version 3.