@puralex/image-audit
v0.3.1
Published
Lint and audit image references in web projects — find broken links, unused images, duplicates, format mismatches, and overused assets.
Downloads
61
Maintainers
Readme
@puralex/image-audit
Lint and audit image references in web projects — find broken links, unused images, duplicates, format mismatches, and overused assets.
Install
npm install @puralex/image-auditCLI
npx image-audit <command> [options]Commands
| Command | Description |
| --------- | ---------------------------------------------- |
| broken | Find broken image references in source files |
| unused | Find unused images in assets directory |
| dupes | Find duplicate images by content hash |
| compat | Verify file extensions match binary format |
| overuse | Find images referenced in multiple source files|
| all | Run all audits (default) |
Options
-c, --config <path> Config file path (default: image-audit.config.js)
-a, --assets <dir> Assets directory (default: src/assets/images)
-s, --src <dir> Source files root (default: src)
-r, --reporter <name> Output format: text | json (default: text)
--no-color Disable colored output
--verbose Verbose output
-h, --help Show this help
-v, --version Show versionExamples
# Run all audits
image-audit
# Run specific audits
image-audit broken unused
# JSON output for CI
image-audit all --reporter json
# Custom paths
image-audit --src pages --assets src/imagesIf your images live somewhere other than src/assets/images, also set pathAliases in the config file (see Configuration). The default aliases map ~/assets/images/ and /assets/images/ to src/assets/images/. References that resolve outside the assets directory are skipped with a scan warning. The CLI prints the warning count; run with --verbose to see each one.
Exit codes
| Code | Meaning |
| ---- | ------------------------------------------------------------------------- |
| 0 | All selected audits passed |
| 1 | At least one audit found issues |
| 2 | Usage or runtime error (bad flag, bad config, missing directory, crash) |
Errors
These stop the run with exit code 2:
Config file not found: <path>— the file given with--configdoes not exist.Source directory not found: <path>—srcDirdoes not exist (checked forbroken,unused,overuse).Assets directory not found: <path>—assetsDirdoes not exist (checked forunused,dupes,compat).Invalid reporter: "<name>"— the reporter is nottextorjson.
Programmatic API
import { lint } from '@puralex/image-audit';
const { ok, results, warnings } = await lint({
projectRoot: './my-project',
audits: ['broken', 'unused'],
});
if (!ok) {
console.error('Image audit failed:', results);
process.exitCode = 1;
}lint() also returns the resolved config. It rejects with an Error for the cases listed under Errors.
Individual audits
import { loadConfig, scanReferences, auditBroken, auditUnused } from '@puralex/image-audit';
const config = await loadConfig({ projectRoot: '.' });
const scan = scanReferences(config);
const broken = auditBroken(config, scan);
const unused = auditUnused(config, scan);Available exports
| Function | Needs scan | Async | Description |
| ------------------ | ---------- | ----- | ------------------------------------ |
| lint(options?) | - | yes | Run selected audits, returns results |
| auditBroken | yes | no | Broken image references |
| auditUnused | yes | no | Unreferenced image files |
| auditDuplicates | no | no | Duplicate images by content hash |
| auditCompat | no | yes | Extension vs binary format mismatch |
| auditOveruse | yes | no | Images referenced too many times |
| loadConfig | - | yes | Load and merge config |
| scanReferences | - | no | Scan source files for image refs |
| findFiles | - | no | Find files by extension |
| normalizePath | - | no | Resolve image path aliases |
Configuration
Create image-audit.config.js in your project root:
export default {
srcDir: 'src',
assetsDir: 'src/assets/images',
sourceExtensions: ['.astro', '.mdx'],
imageExtensions: ['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.avif'],
imagePathPatterns: [/(['"`])((~\/assets\/images\/|\/assets\/images\/)[^'"`]+)\1/g],
pathAliases: {
'~/assets/images/': 'src/assets/images/',
'/assets/images/': 'src/assets/images/',
},
overuseThreshold: 1,
reporter: 'text', // 'text' | 'json'; --reporter overrides it
noColor: false, // also set by --no-color or a non-empty NO_COLOR env var
verbose: false,
};Priority: defaults < config file < CLI flags.
Or in package.json:
{
"imageAudit": {
"srcDir": "src",
"assetsDir": "public/images",
"pathAliases": {
"/images/": "public/images/"
},
"imagePathPatterns": ["(['\"`])(/images/[^'\"`]+)\\1"]
}
}Optional: sharp
Install sharp for image dimension and aspect ratio detection in the compat audit:
npm install sharpDevelopment
npm test # generate fixtures and run the test suite
npm run lint # Biome: lint + format check (same as CI)
npm run format # Biome: apply formatting and safe fixesLicense
MIT
