imagepreparation-lazy-srcset 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# imagepreparation-lazy-srcset
+
+This package was created specifically to prepare photos for use with the [`lazy-srcset`](https://www.npmjs.com/package/lazy-srcset) package.
+
+A Node.js library + CLI that prepares a folder of source photos for the [`lazy-srcset`](https://www.npmjs.com/package/lazy-srcset) frontend lazy-loading pattern.
+
+It resizes every image down to a set of responsive breakpoints, re-encodes each one to a modern format (`webp` by default), and stores everything in a content-addressable store so identical work is never redone. Each photo is content-hashed, organized into its own hash-named folder, and (optionally) "published" into the exact filename convention `lazy-srcset` expects on the frontend.
+
+## Features
+
+- **Responsive breakpoints** — resizes each source image to multiple widths (default: `1920, 1440, 1280, 1024, 768, 640, 480, 320`) without ever upscaling.
+- **Modern formats** — re-encodes to `webp` (or any format `sharp` supports) at a configurable quality.
+- **Content-addressable storage** — resized variants are stored by content hash; running the tool again never duplicates work or storage.
+- **Content-based deduplication** — two uploaded photos with identical bytes (even under different filenames) collapse into a single processed entry.
+- **Resumable manifest** — a single `.img-manifest.json` per collection tracks what's already been processed, so interrupted or repeated runs pick up where they left off.
+- **Originals are preserved**, not deleted — each source photo is kept (renamed) next to its generated variants, so future re-encodes (different quality/format/breakpoints) don't need the original upload again.
+- **`lazy-srcset`-ready output** — an explicit publish step links generated variants into the exact `name-{width}.{ext}` sibling-file convention the frontend package expects.
+
+## Installation
+
+```bash
+npm install imagepreparation-lazy-srcset
+```
+
+This installs the `image-preparation` CLI binary. `sharp` is the only runtime dependency.
+
+## CLI usage
+
+```bash
+image-preparation <imagesDir> [options]
+```
+
+or, without installing the bin globally:
+
+```bash
+node bin/cli.js <imagesDir> [options]
+```
+
+| Argument / Flag | Default | Description |
+| - | - | - |
+| `imagesDir` (positional) | `./img` | Folder containing the source photos (or path to a single image file). |
+| `--format` | `webp` | Output format passed to `sharp` (e.g. `webp`, `avif`). |
+| `--quality` | `82` | Encoding quality for the output format. |
+| `--breakpoints` | `1920,1440,1280,1024,768,640,480,320` | Comma-separated list of target widths, in pixels. |
+| `--publish` | off | After processing, link the generated variants into the `lazy-srcset` naming convention (see below). |
+
+### Example
+
+```bash
+image-preparation ./img --format webp --quality 80 --breakpoints 1600,1200,800,400 --publish
+```
+
+## How it works
+
+1. **Discovery** — `<imagesDir>` is scanned for source images. Loose image files directly inside it, and one level of subfolders, are picked up as input. Already-known bucket folders (see below) and `_`-prefixed folders are skipped, so the tool's own output is never mistaken for new source material on the next run.
+
+2. **Content hashing** — each source file's *content* is SHA-1 hashed. That hash becomes both the photo's manifest key and its working folder name: `<imagesDir>/<hash>/`. Because the hash is based on content, uploading the same photo twice under different names always resolves to the same folder.
+
+3. **Resize + encode** — for every configured breakpoint, the image is resized (`withoutEnlargement: true`, so small originals are never blown up) and re-encoded to the target format/quality. If a resize produces byte-identical output to the previous (larger) breakpoint — common once the source is smaller than a given width — the existing variant is reused instead of storing a duplicate.
+
+4. **Content-addressable store (CAS)** — every resized variant is saved into `<hash>/.store/<h0:2>/<h2:4>/<variantHash>.<format>`, keyed by its own content hash. A variant already on disk is never rewritten.
+
+5. **Original preserved** — the source file is moved (not deleted) into its bucket folder as `<hash>.<originalExt>`, so it survives for future re-processing (e.g. with different quality/format/breakpoints).
+
+6. **Manifest** — a single `<imagesDir>/.img-manifest.json` records, per photo hash, the `{ width: variantHash }` map. This is the durable record that makes re-runs skip already-processed photos.
+
+7. **Publish (`--publish`)** — hard-links (falling back to a copy across filesystems) every CAS-stored variant out to `<hash>/<hash>-<width>.<format>`, right next to the preserved original. Already-correct links are left untouched, so publishing again after adding one new photo only touches that photo's folder.
+
+### Output layout
+
+After processing and publishing a single photo, its folder looks like this:
+
+```
+img/
+└── 2c905c69d5921635fcb59f8176c508c3ff806f4b/
+    ├── .store/                                         # content-addressable, internal
+    │   └── 84/27/84279ca394ec...webp
+    ├── 2c905c69d5921635fcb59f8176c508c3ff806f4b.jpg     # preserved original
+    ├── 2c905c69d5921635fcb59f8176c508c3ff806f4b-320.webp
+    ├── 2c905c69d5921635fcb59f8176c508c3ff806f4b-480.webp
+    ├── 2c905c69d5921635fcb59f8176c508c3ff806f4b-640.webp
+    ├── 2c905c69d5921635fcb59f8176c508c3ff806f4b-768.webp
+    ├── 2c905c69d5921635fcb59f8176c508c3ff806f4b-1024.webp
+    ├── 2c905c69d5921635fcb59f8176c508c3ff806f4b-1280.webp
+    ├── 2c905c69d5921635fcb59f8176c508c3ff806f4b-1440.webp
+    └── 2c905c69d5921635fcb59f8176c508c3ff806f4b-1920.webp
+```
+
+## Using the output with `lazy-srcset`
+
+[`lazy-srcset`](https://www.npmjs.com/package/lazy-srcset) builds its `srcset` by appending `-{width}.{ext}` directly to whatever path is in an image's `data-srcset` attribute — it has no awareness of this tool's internal hashing. Point `data-srcset` at the published path for that photo's hash:
+
+```html
+<img
+  class="lazy-srcset"
+  alt=""
+  src="data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 9"%3E%3C/svg%3E"
+  data-srcset="img/2c905c69d5921635fcb59f8176c508c3ff806f4b/2c905c69d5921635fcb59f8176c508c3ff806f4b.webp"
+/>
+```
+
+`lazy-srcset` will then resolve `…-320.webp`, `…-480.webp`, … `…-1920.webp` automatically. The hash for a given source photo can be looked up from `.img-manifest.json` (it's the top-level key).
+
+## Programmatic API
+
+```js
+import { imagePipeline } from 'imagepreparation-lazy-srcset';
+
+await imagePipeline({
+  imagesCollectionDir: './img', // folder or single file path
+  format: 'webp',
+  quality: 82,
+  breakpoints: [1920, 1440, 1280, 1024, 768, 640, 480, 320],
+  inputFormats: ['jpg', 'jpeg', 'png', 'webp', 'avif'],
+  publish: true,
+});
+```
+
+All options are optional and merge over the defaults shown above.
+
+## Status
+
+This is an early, actively-evolving package — there is no test suite, lint config, or type checker yet. Planned next steps include manifest versioning, a garbage collector for orphaned `.store` entries, and incremental rebuilds that skip files whose settings haven't changed.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { imagePipeline } from '../src/index.js';
+
+const args = process.argv.slice(2);
+
+function getArg(flag, defaultValue) {
+    const index = args.indexOf(flag);
+    if (index === -1) return defaultValue;
+    return args[index + 1];
+}
+
+const dir = args[0] || './img';
+
+const format = getArg('--format', 'webp');
+const quality = Number(getArg('--quality', 82));
+
+const breakpoints = getArg('--breakpoints', '1920, 1440, 1280, 1024, 768, 640, 480, 320')
+    .split(',')
+    .map(Number);
+
+const publish = args.includes('--publish');
+
+await imagePipeline({
+    imagesCollectionDir: dir,
+    format,
+    quality,
+    breakpoints,
+    publish,
+}).catch(console.error);

package/dist/imagePreparation.min.js

@@ -0,0 +1 @@
+import fs from"fs/promises";import path from"path";import{processFolder}from"./processFolder.js";import{loadManifest}from"./manifest.js";const defaults={breakpoints:[1920,1440,1280,1024,768,640,480,320],imagesCollectionDir:"img",format:"webp",quality:82,inputFormats:["jpg","jpeg","png","webp","avif"],publish:!1};export async function imagePipeline(e={}){const s={...defaults,...e},t=path.resolve(s.imagesCollectionDir);if((await fs.stat(t)).isFile())return processFolder([t],s,path.dirname(t));const i=t,o=await loadManifest(i),a=new Set(Object.keys(o.files)),r=await fs.readdir(i,{withFileTypes:!0}),n=[],p=[];for(const e of r){const s=path.join(i,e.name);if(e.isDirectory()){if(e.name.startsWith("_")||a.has(e.name))continue;n.push(s)}else p.push(s)}p.length>0&&await processFolder(p,s,i);for(const e of n)await processFolder(e,s,i)}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "imagepreparation-lazy-srcset",
+  "version": "0.1.0",
+  "homepage": "",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "type": "module",
+  "main": "./dist/lazy-srcset.min.js",
+  "exports": {
+    ".": "./dist/lazy-srcset.min.js"
+  },
+  "description": "Automatically prepare fotos for lazy-srcset npm plugin",
+  "author": "",
+  "scripts": {
+    "build": "terser src/index.js -o dist/imagePreparation.min.js -c -m"
+  },
+  "bin": {
+    "image-preparation": "bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "lazyload",
+    "lazy-loading",
+    "images",
+    "responsive-images",
+    "srcset",
+    "webp",
+    "avif",
+    "placeholder",
+    "intersection-observer",
+    "performance",
+    "pagespeed",
+    "lighthouse",
+    "core-web-vitals",
+    "cls",
+    "lcp",
+    "wordpress",
+    "vue",
+    "nuxt",
+    "react",
+    "javascript"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "terser": "^5.48.0"
+  },
+  "dependencies": {
+    "sharp": "^0.35.1"
+  }
+}