No More Broken Image Paths! Meet assets-mapper for React & Next.js 🚀

#react #nextjs #npm #opensource

Have you ever changed an image in your project and suddenly half your UI broke because of that one annoying error?

Module not found: Can't resolve '../assets/logo.png'

Yeah, me too 😩
After facing this frustration again and again, I decided to automate the entire process.

The Problem

In React or Next.js projects, developers often face:

Tedious manual imports for every image
Long relative paths like (../../../assets/...)
Errors when moving or renaming image files
Inconsistent paths across components
Time wasted fixing broken imports

Every time you reorganize your assets folder, something breaks. It’s messy, repetitive, and completely avoidable.

The Solution — assets-mapper 🚀

assets-mapper automatically scans your image folders and generates a TypeScript-safe asset map — so you never have to deal with broken paths again.

Instead of writing:

import logo from '../../assets/images/logo.png';

You can now write:

import { logo } from 'assets-mapper';

That’s it.
No configuration. No path issues. Works beautifully with both React and Next.js.

Why assets-mapper?

✅ No more broken paths — catch missing assets at build time
✅ TypeScript autocomplete — IntelliSense for your images
✅ Smart duplicate handling — adds folder prefixes only when needed
✅ File watching — automatically regenerates when assets change
✅ Framework agnostic — works with React, Next.js, Vue, and more
✅ Zero configuration — works out of the box

Installation

npm install assets-mapper

Quick Start

CLI Usage

# Basic usage
npx assets-mapper --src src/assets --out src/assetsMap.js

# With file watching (recommended for development)
npx assets-mapper --src src/assets --out src/assetsMap.js --watch

# For Next.js public folder
npx assets-mapper --src public/images --out src/assetsMap.js --public

Programmatic Usage

const { generateAssetsMap } = require('assets-mapper');

const result = generateAssetsMap({
  src: 'src/assets',
  out: 'src/assetsMap.js'
});

console.log(`✅ Generated map with ${result.totalFiles} assets`);

Example

Your folder structure:

src/assets/
├── logo.png
├── hero.jpg
├── icons/
│   ├── home.svg
│   └── logo.png
└── images/
    └── banner.webp

Generated assetsMap.js:

import logo from "./assets/logo.png";
import hero from "./assets/hero.jpg";
import home from "./assets/icons/home.svg";
import icons_logo from "./assets/icons/logo.png";
import banner from "./assets/images/banner.webp";

const assetsMap = {
  logo,
  hero,
  home,
  icons_logo,
  banner
};

export default assetsMap;

Use it in your components:

import assetsMap from './assetsMap.js';

function Header() {
  return (
    <header>
      <img src={assetsMap.logo} alt="Logo" />
      <img src={assetsMap.hero} alt="Hero" />
    </header>
  );
}

Smart Features

Duplicate Handling: Adds folder prefixes only when filenames conflict
File Watching: Automatically regenerates when you add, remove, or rename assets
Auto-cleanup: Removes generated files when the package is uninstalled
TypeScript support: Full autocomplete and safety in editors

Requirements