img-src-placeholder

Replace src=# in <img> tags of HTML files with an inline Base64 data URL of a transparent 1 pixel image (CLI tool designed for use in npm package.json scripts)

img-src-placeholder solves the trickly little problem that valid HTML requires that all <img> tags have a src attribute even if your web application sets the src attribute dynamically.

This tool transforms:

<img src=# alt=avatar>

into:

<img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxIiBoZWlnaHQ9IjEiPjwvc3ZnPg=="
   alt=avatar>

A) Setup

Install package for node:

$ npm install --save-dev img-src-placeholder

B) Usage

1. npm package.json scripts

Run img-src-placeholder from the "scripts" section of your package.json file.

Parameters:

The first parameter is the source folder or file.
The second parameter is the target folder.

Example package.json scripts:

   "scripts": {
      "stage-web": "img-src-placeholder src/web build/website",
   },

2. Command-line npx

Example terminal commands:

$ npm install --save-dev img-src-placeholder
$ npx img-src-placeholder src/web ext=.html docs/api-manual

You can also install img-src-placeholder globally (--global) and then run it anywhere directly from the terminal.

3. CLI flags

Command-line flags:

Flag	Description	Value
`--cd`	Change working directory before starting search.	string
`--ext`	Filter files by file extension, such as `.html`. Use a comma to specify multiple extensions.	string
`--note`	Place to add a comment only for humans.	string
`--quiet`	Suppress informational messages.	N/A
`--summary`	Only print out the single line summary message.	N/A

The default value for --ext is: ".html,.htm,.php,.aspx,.asp,.jsp"

4. Example CLI usage

Examples:

img-src-placeholder src/web build/website
Recursively copies all HTML files in the src/web folder to the build/website folder and replaces the "hash" placeholder image sources with an inline data URL for a transparent 1 pixel image.
img-src-placeholder src/web build/website --summary
Displays the summary but not the individual files copied.
img-src-placeholder src/web build/website --ext=.php
Only processes PHP files.
img-src-placeholder src/web 'build/Website Root' --ext=.php
Specifies a destination folder that has a space in its name.

Note: Single quotes in commands are normalized so they work cross-platform and avoid the errors often encountered on Microsoft Windows.

C) Application Code

Even though img-src-placeholder is primarily intended for build scripts, the package can be used programmatically in ESM and TypeScript projects.

Example:

import { imgSrcPlaceholder } from 'img-src-placeholder';

const options = { extensions: ['.html'] };
const results = imgSrcPlaceholder.transform('src/web', 'build', options);
console.log('Number of files copied:', results.count);

See the TypeScript Declarations at the top of img-src-placeholder.ts for documentation.

D) Under the Hood

The data URL is created by Base64 encoding a super simple <svg> string:

const onePixelSvg =
   '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"></svg>';
const dataImage = 'data:image/svg+xml;base64,' +
   Buffer.from(onePixelSvg).toString('base64');

CLI Build Tools for package.json

🎋 add-dist-header: Prepend a one-line banner comment (with license notice) to distribution files
📄 copy-file-util: Copy or rename a file with optional package version number
📂 copy-folder-util: Recursively copy files from one folder to another folder
🪺 recursive-exec: Run a command on each file in a folder and its subfolders
🔍 img-src-placeholder: Find and replace strings or template outputs in text files
🔢 rev-web-assets: Revision web asset filenames with cache busting content hash fingerprints
🚆 run-scripts-util: Organize npm package.json scripts into groups of easy to manage commands
🚦 w3c-html-validator: Check the markup validity of HTML files using the W3C validator

Feel free to submit questions at:
github.com/center-key/img-src-placeholder/issues

MIT License