npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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

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-audit

CLI

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 version

Examples

# 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/images

If 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 --config does not exist.
  • Source directory not found: <path> — srcDir does not exist (checked for broken, unused, overuse).
  • Assets directory not found: <path> — assetsDir does not exist (checked for unused, dupes, compat).
  • Invalid reporter: "<name>" — the reporter is not text or json.

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 sharp

Development

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 fixes

License

MIT