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

Nauman Majeed — Thu, 09 Oct 2025 11:47:20 +0000

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

Node.js 14+
Works with React, Next.js, Vue, Svelte, and any JavaScript or TypeScript project

Made for Developers

Built with one simple goal:

Save developers from the pain of broken image paths.

Made with ❤️ for developers who just want things to work smoothly.

Links
npm: https://www.npmjs.com/package/assets-mapper
GitHub: https://github.com/inaumanmajeed/assets-mapper

From Business Student to Frontend Developer: Building My First Open-Source Project

Nauman Majeed — Sat, 23 Aug 2025 20:14:09 +0000

Two years ago, I was a business student following the “safe” path. But something didn’t feel right — I wanted to build things, not just study them. So I took a leap, switched careers, and started teaching myself web development.

Fast forward to today, I’m excited to share my first open-source project on npm:

👉 filters-query-params
A lightweight TypeScript library for effortless URL state management in web apps.

🌱 My Journey in a Nutshell

Quit my business career to pursue software development.
Learned the fundamentals through tutorials, docs, and small projects.
Got my first chance as an intern.
Thanks to amazing mentorship from from my seniors, I learned not just coding but problem-solving.
Earned a promotion and officially kickstarted my development career.

⚡ The Problem I Wanted to Solve

Managing URL query parameters for filters (think search filters, dashboards, e-commerce, etc.) can get messy:

Syncing state with the URL
Validating query parameters
Debouncing to avoid unnecessary calls
Keeping code clean and maintainable

I wanted a framework-agnostic, TypeScript-first solution that just works.

🛠️ Introducing `filters-query-params`

A simple but powerful library to handle URL filters in your applications.

Features:

✅ Sync filters with URL query parameters automatically
✅ Full TypeScript support
✅ Built-in Zod validation for runtime safety
✅ Framework agnostic (works with React, Next.js, or vanilla JS)
✅ Automatic debouncing & smart data handling
✅ Zero configuration for quick adoption

🚀 Installation & Usage

npm install filters-query-params zod

Example with React + Zod

import { useFilters } from "filters-query-params";
import { z } from "zod";

const schema = z.object({
  search: z.string().optional(),
  category: z.string().optional(),
});

export default function App() {
  const { filters, setFilter } = useFilters(schema);

  return (
    <div>
      <input
        value={filters.search || ""}
        onChange={(e) => setFilter("search", e.target.value)}
        placeholder="Search..."
      />
      <button onClick={() => setFilter("category", "books")}>
        Books
      </button>
    </div>
  );
}

That’s it — your filters now sync with the URL and validate automatically!

💡 Why This Project Matters to Me

This isn’t just about code.
Every function, every test, and every line represents my journey:
from a business student ➝ frontend developer ➝ open-source contributor.

It’s proof that with passion, persistence, and mentorship, you can reinvent yourself.

🙌 How You Can Help

If you find this useful, I’d love your support:

⭐ Star it on GitHub
🔄 Try it in your project
💬 Share feedback, issues, or suggestions

Together, let’s make filter state management simple for everyone.

Forem: Nauman Majeed