How to Deploy & Use desandro/imagesloaded

# imagesLoaded Deployment & Usage Guide

## 1. Prerequisites

- **Node.js** v14+ (required for building packaged distributions)
- **npm** or **Yarn** (for package management)
- **Modern web browser** (Chrome, Firefox, Safari, Edge) for testing
- **Git** (for cloning the repository)

## 2. Installation

### For Library Users

**Via CDN (Recommended for quick usage):**
```html
<script src="https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.min.js"></script>

Via npm/Yarn:

npm install imagesloaded
# or
yarn add imagesloaded

Direct Download:

imagesloaded.pkgd.min.js (minified)
imagesloaded.pkgd.js (un-minified)

For Contributors/Developers

git clone https://github.com/desandro/imagesloaded.git
cd imagesloaded
npm install

This installs the development dependency (ev-emitter) required for building.

3. Configuration

No environment variables or external configuration files are required. Configuration is passed as an options object when initializing:

// Background image detection
imagesLoaded('#container', { background: true }, callback);

// Detect background images on child elements
imagesLoaded('#container', { background: '.item' }, callback);

Available Options:

background (Boolean|String): Set to true to detect element background images, or provide a selector string (e.g., '.item') to detect background images on child elements.

4. Build & Run

Building the Packaged Distribution

The repository source requires ev-emitter as a dependency. To create the standalone packaged files (imagesloaded.pkgd.js and imagesloaded.pkgd.min.js):

node tasks/dist.js

This script:

Concatenates node_modules/ev-emitter/ev-emitter.js with imagesloaded.js
Adds the banner and "PACKAGED" suffix
Minifies the output using Terser
Outputs to imagesloaded.pkgd.js and imagesloaded.pkgd.min.js

Local Development/Testing

Serve the sandbox files with a local HTTP server (required for proper image loading):

# Using Python 3
python -m http.server 8000

# Using Node.js (npx)
npx serve .

# Using PHP
php -S localhost:8000

Then open http://localhost:8000/sandbox/progress/ to test the progress demo.

Usage in Projects

Vanilla JavaScript:

// Selector string
imagesLoaded('#container', function(instance) {
  console.log('All images loaded');
});

// Element reference
var elem = document.querySelector('#container');
imagesLoaded(elem, { background: true }, function(instance) {
  console.log('Images and backgrounds loaded');
});

With jQuery:

$('#container').imagesLoaded(function() {
  // images have loaded
});

// With Deferred methods
$('#container').imagesLoaded()
  .always(function(instance) { console.log('All images loaded'); })
  .done(function(instance) { console.log('All images successfully loaded'); })
  .fail(function() { console.log('One or more images broken'); })
  .progress(function(instance, image) {
    var result = image.isLoaded ? 'loaded' : 'broken';
    console.log('Image is ' + result);
  });

ES Modules/CommonJS:

// CommonJS
const imagesLoaded = require('imagesloaded');

// ES Modules (with bundler)
import imagesLoaded from 'imagesloaded';

5. Deployment

Publishing the Library (Maintainers)

npm version patch|minor|major
npm publish

Deploying to Production (Users)

Static Site/CDN: Include the CDN link in your HTML before your application code:

<script src="https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.min.js"></script>
<script src="your-app.js"></script>

Bundled Applications: If using Webpack, Rollup, or Vite:

import imagesLoaded from 'imagesloaded';

// Use in your app
imagesLoaded(gridElement, function() {
  // Initialize masonry or other layout
});

npm Package Deployment: The library is ready for use in Node.js-based build systems after npm install. No additional build step is required for the end user.

6. Troubleshooting

Images not detected

Issue: imagesLoaded fires immediately without detecting images.
Solution: Ensure the DOM is ready before calling. If using dynamically added images, call imagesLoaded after insertion into the DOM.

Cross-Origin (CORS) Errors

Issue: "Cross-origin image loaded" warnings or broken detection for external images.
Solution: The library can detect loading status but cannot inspect pixel data of cross-origin images. Ensure external images have proper Access-Control-Allow-Origin headers if you need detailed information.

Background images not detected

Issue: Background images aren't triggering the loaded event.
Solution: Verify you're using the background: true option. Note that the library detects background images set via inline styles or CSS, but the element must be in the DOM.

jQuery plugin not working

Issue: $('#container').imagesLoaded is not a function
Solution: Ensure jQuery is loaded before imagesLoaded. The library auto-detects jQuery (window.jQuery) and registers the plugin automatically.

Broken image detection

Issue: Need to identify which specific images failed.
Solution: Use the progress event to check individual image status:

imgLoad.on('progress', function(instance, image) {
  if (!image.isLoaded) {
    console.error('Broken image:', image.img.src);
  }
});

Build fails with "Cannot find module 'ev-emitter'"

Issue: node tasks/dist.js throws module error.
Solution: Run npm install first to install the ev-emitter dependency.

npm install
node tasks/dist.js