@eltkof7/webimg-cli

CLI TypeScript pour optimiser, convertir et générer des images web prêtes pour la production.

• Conversion vers webp, avif, jpeg et png avec Sharp.
• Scan des images png, jpg, jpeg, tiff, webp et avif.
• Conversion multi-formats en une commande: --format webp,avif.
• Redimensionnement simple avec --resize et plafond avec --max-width.
• Variantes responsive @1x, @2x, @3x avec --responsive.
• Dossier de sortie configurable avec conservation de l'arborescence depuis --input.
• Protection contre l'ecrasement du fichier source.
• Les sorties generees ne sont pas rescanees comme entrees.
• Metadata EXIF strippees par defaut, avec option --keep-metadata.
• Cache .webimg-cache.json invalide quand le fichier source ou les options changent.
• Mode --watch pour relancer la conversion pendant le developpement.
• Rapport console, JSON ou Markdown.
• Suppression sûre avec backup optionnel et nettoyage des sorties orphelines.
• Limite de concurrence configurable.
• API programmatique utilisable dans un script Node.js.

• Node.js >=18
• npm >=9 recommande

Verifier la version locale:

node -v
npm -v

Installation globale:

npm install -g @eltkof7/webimg-cli
webimg --version

Utilisation sans installation globale:

npx @eltkof7/webimg-cli --version
npx @eltkof7/webimg-cli scan -r

Installation dans un projet:

npm install -D @eltkof7/webimg-cli
npx webimg scan -r

Exemple de scripts npm:

{
  "scripts": {
    "img:scan": "webimg scan -i ./src/assets -r",
    "img:build": "webimg run -i ./src/assets -o ./public/img -f webp,avif -q 80 -r",
    "img:watch": "webimg run -i ./src/assets -o ./public/img -f webp --watch -r"
  }
}

Mode interactif:

webimg

Creer une configuration par defaut:

webimg init

Scanner le dossier courant:

webimg scan
webimg scan -r

Scanner un dossier precis:

webimg scan -i ./src/assets -r

Convertir en WebP dans le meme dossier:

webimg run -f webp -q 80 -r

Convertir vers WebP et AVIF dans un dossier public:

webimg run -i ./src/assets -o ./public/img -f webp,avif -q 80 -r

Generer des variantes responsive:

webimg run -i ./src/assets -o ./public/img -f webp,avif --resize 800 --responsive 1,2,3 -r

Tester sans ecrire de fichiers:

webimg run -i ./src/assets -f avif --dry-run --report report.md -r

Surveiller les changements:

webimg run -i ./src/assets -o ./public/img -f webp --watch -r

Lance le mode interactif. Le CLI pose quelques questions, scanne les images, puis lance la conversion.

webimg

Cree webimg.config.json dans le dossier courant.

webimg init

Scanne les images et affiche un resume par extension.

webimg scan -i ./src/assets -r

Options utiles:

webimg scan --include "images/**/*.{png,jpg}" --exclude "**/*.raw.png"

Execute la conversion sans question interactive. C'est la commande a utiliser en CI/CD ou dans les scripts npm.

webimg run -i ./src/assets -o ./public/img -f webp,avif -q 80 -r

webimg run -i ./src/assets -o ./public/img -f webp --replace --backup --backup-dir ./backups -r

La source n'est supprimee qu'apres conversion complete et copie reussie dans le backup. En cas d'erreur, elle est conservee.

webimg run -i ./src/assets -o ./public/img -f webp --clean -r

--clean ne supprime que les fichiers de formats declares qui correspondent a des sorties generees et ne sont plus planifies.

webimg run -i ./src/assets -o ./public/img -f webp,avif -q 78 -r

Si src/assets/products/shoe.png existe, les sorties seront:

public/img/products/shoe.webp
public/img/products/shoe.avif

webimg run -i ./images -f webp -s .min -r

Sortie exemple:

images/photo.min.webp

webimg run -i ./images -o ./public/img -f webp --resize 1200 -r

Les images plus petites que 1200px ne sont pas agrandies.

webimg run -i ./images -o ./public/img -f webp --resize 640 --responsive 1,2,3 -r

Sorties exemple:

public/img/[email protected]  # 640px
public/img/[email protected]  # 1280px
public/img/[email protected]  # 1920px

webimg run -i ./images -o ./public/img -f avif --resize 1600 --max-width 1200 -r

webimg run -i ./images -o ./public/img -f webp,avif --report report.json -r
webimg run -i ./images -o ./public/img -f webp,avif --report report.md -r

webimg run --include "src/**/*.{png,jpg}" --exclude "**/*.icon.png,**/raw/**" -f webp

webimg run -i ./images -f webp --replace -r

Utiliser --replace seulement si les sources peuvent etre supprimees. Le CLI refuse d'ecrire une sortie sur le meme chemin que le fichier source; utilisez --output ou --suffix si necessaire.

Creer le fichier:

webimg init

Exemple webimg.config.json:

{
  "input": "./src/assets",
  "output": "./public/img",
  "recursive": true,
  "formats": ["webp", "avif"],
  "quality": 80,
  "resize": 1200,
  "maxWidth": null,
  "responsive": [1, 2],
  "suffix": "",
  "keepMetadata": false,
  "keepOriginal": true,
  "include": [],
  "exclude": ["**/node_modules/**", "**/dist/**"],
  "cache": true,
  "dryRun": false
}

Les options passees en ligne de commande surchargent la configuration du fichier.

Fichiers de configuration supportes:

webimg.config.json
.webimgrc.json
.webimgrc

Le cache est stocke dans .webimg-cache.json.

Une conversion est reutilisee seulement si:

• le fichier source n'a pas change;
• les sorties attendues existent;
• les options de conversion importantes sont identiques: formats, qualite, resize, max-width, responsive, suffixe et metadata.

Desactiver le cache:

webimg run -i ./images -f webp --no-cache -r

Par defaut, les metadata EXIF/IPTC/XMP sont retirees.

Conserver les metadata:

webimg run -i ./images -f webp --keep-metadata -r

import { findImages, mergeConfig, runParallel, summarize } from '@eltkof7/webimg-cli';

const cwd = process.cwd();
const cfg = mergeConfig({
  input: './src/assets',
  output: './public/img',
  recursive: true,
  formats: ['webp', 'avif'],
  quality: 80,
  resize: 1200,
});

const files = await findImages(cwd, cfg);
const results = await runParallel(files, cfg, cwd);
const summary = summarize(results);

console.log(summary);

Exports disponibles:

export { convertFile, runParallel } from '@eltkof7/webimg-cli';
export { findImages, SUPPORTED_INPUT } from '@eltkof7/webimg-cli';
export { loadConfig, mergeConfig, DEFAULT_CONFIG } from '@eltkof7/webimg-cli';
export { summarize, printReport, writeJsonReport, writeMarkdownReport, formatBytes } from '@eltkof7/webimg-cli';
export { ConversionCache } from '@eltkof7/webimg-cli';

Cloner le depot:

git clone https://github.com/REBCDR07/webimg-cli.git
cd webimg-cli

Installer les dependances:

npm install

Lancer les controles:

npm run lint
npm run typecheck
npm test
npm run build
npm audit

Tester le binaire local:

npm run build
node dist/index.js --version
node dist/index.js scan -r

Tester globalement avec npm link:

npm link
webimg --version
webimg scan -r

Verifier le contenu du package npm:

npm pack --dry-run

Verifier l'authentification:

npm whoami

Publier une nouvelle version:

npm version patch
git push --follow-tags
npm publish --access public

Pour une premiere publication du package scope public:

npm publish --access public

Le hook prepublishOnly lance automatiquement:

npm run lint
npm run typecheck
npm test
npm run build

Le workflow GitHub Actions execute lint, typecheck, tests et build sur Node 18, 20 et 22.

La publication automatique peut etre faite depuis une release GitHub avec un secret NPM_TOKEN configure dans les settings du depot.

MIT © eltkof7