react-assets-gen

React Assets Gen

Production-ready React Assets Code Generator - Type-safe asset imports for React projects.

Features

✨ Type-Safe - Generate strongly-typed TypeScript definitions for all your assets
🔄 Watch Mode - Automatically regenerate on file changes
📁 Nested Structure - Maintains your folder hierarchy in the generated code
🎨 SVG Support - Optional React component exports for SVGs (works with Vite/SVGR)
⚙️ Configurable - JSON configuration file support
🚀 Production Ready - Clean, well-typed, production-grade code
📦 Zero Runtime Dependencies - Generated file has no runtime dependencies

Supported Asset Types

• Images: .png, .jpg, .jpeg, .webp, .gif, .avif
• SVG: .svg (with optional React component export)
• Fonts: .woff, .woff2, .ttf, .otf, .eot
• Videos: .mp4, .webm, .ogg
• Audio: .mp3, .wav, .ogg, .m4a

Installation

As a Dev Dependency (Recommended)

# Using npm
npm install --save-dev react-assets-gen

# Using pnpm
pnpm add -D react-assets-gen

# Using yarn
yarn add -D react-assets-gen

Global Installation

npm install -g react-assets-gen

Quick Start

1. Create Assets Directory

Create an assets/ folder in your project root:

my-react-app/
├── assets/
│   ├── images/
│   │   ├── logo.png
│   │   └── hero-bg.webp
│   ├── icons/
│   │   ├── close.svg
│   │   └── menu.svg
│   └── fonts/
│       └── custom-font.woff2
├── src/
└── package.json

2. Run the Generator

# If installed locally
npx assets-gen

# If installed globally
assets-gen

3. Use Generated Assets

import { Assets } from '@/generated/assets';

function App() {
  return (
    <div>
      <img src={Assets.images.logo} alt="Logo" />
      <img src={Assets.images.heroBg} alt="Hero" />
    </div>
  );
}

4. Use SVG Components (Optional)

If SVG components are enabled:

import { SvgComponents } from '@/generated/assets';

function Header() {
  return (
    <header>
      <SvgComponents.icons.menu />
      <SvgComponents.icons.close />
    </header>
  );
}

Configuration

Create an assets-gen.config.json file in your project root:

{
  "assetsDir": "src/assets",
  "output": "src/generated/assets.ts",
  "svg": {
    "asComponent": true
  },
  "verbose": false
}

You can place your assets in any folder you like—just update the assetsDir path accordingly.

• assetsDir: Directory containing your assets (images, icons, SVGs).
• output: Path to the generated TypeScript file.
• svg.asComponent: Set to true to generate React components for SVGs.
• verbose: Set to true to log detailed information during generation.

Configuration Options

Option	Type	Default	Description
assetsDir	string	"assets"	Directory containing your assets (relative to project root)
output	string	"src/generated/assets.ts"	Output file path (relative to project root)
svg.asComponent	boolean	true	Generate React component exports for SVGs
verbose	boolean	false	Enable verbose logging

CLI Usage

assets-gen [options]

Options

Option	Description
-c, --config <path>	Path to config file
-w, --watch	Watch assets directory for changes
-v, --verbose	Enable verbose logging
--assets-dir <path>	Assets directory (overrides config)
--output <path>	Output file path (overrides config)
--version	Show version number
--help	Show help

Examples

# Generate once
assets-gen

# Watch mode (auto-regenerate on changes)
assets-gen --watch

# Custom config file
assets-gen --config custom-config.json

# Override assets directory
assets-gen --assets-dir public/assets

# Verbose output
assets-gen --verbose

Integration with Build Tools

Vite

For SVG React components to work with Vite, install vite-plugin-svgr:

npm install --save-dev vite-plugin-svgr

Update vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import svgr from 'vite-plugin-svgr';

export default defineConfig({
  plugins: [
    react(),
    svgr(), // Enable SVG as React components
  ],
});

Package.json Scripts

Add scripts to your package.json:

{
  "scripts": {
    "assets:gen": "assets-gen",
    "assets:watch": "assets-gen --watch",
    "predev": "assets-gen",
    "prebuild": "assets-gen"
  }
}

This ensures assets are generated before dev/build.

Generated File Structure

Given this asset structure:

assets/
├── images/
│   ├── logo.png
│   └── products/
│       └── item-1.jpg
└── icons/
    └── close.svg

The generated src/generated/assets.ts will look like:

/**
 * AUTO-GENERATED FILE - DO NOT EDIT
 * Generated by react-assets-gen
 * Generated at: 2025-12-14T17:30:00.000Z
 */

import closeSvgComponent from '../../assets/icons/close.svg?react';

export interface AssetsType {
  readonly images: {
    readonly logo: string;
    readonly products: {
      readonly item1: string;
    };
  };
  readonly icons: {
    readonly close: string;
  };
}

export const Assets: AssetsType = {
  images: {
    logo: '../../assets/images/logo.png',
    products: {
      item1: '../../assets/images/products/item-1.jpg',
    },
  },
  icons: {
    close: '../../assets/icons/close.svg',
  },
} as const;

export const SvgComponents = {
  close: closeSvgComponent,
} as const;

export default Assets;

Naming Conventions

File names are converted to camelCase identifiers:

File Name	Generated Identifier
logo.png	logo
hero-image.jpg	heroImage
user_avatar.png	userAvatar
icon-2024.svg	icon2024
my-logo.png	myLogo

TypeScript Path Aliases

For cleaner imports, configure path aliases in tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Then import like:

import { Assets } from '@/generated/assets';

Best Practices

• Commit Generated Files - Commit src/generated/assets.ts to version control for consistency
• Pre-build Generation - Add assets-gen to your prebuild script
• Watch Mode in Dev - Run assets-gen --watch during development
• Organize Assets - Use folders to organize assets by type/feature
• Optimize Assets - Compress images before adding to assets folder

Troubleshooting

SVG Components Not Working

Make sure you have vite-plugin-svgr installed and configured:

npm install --save-dev vite-plugin-svgr

Module Not Found Errors

Check that:

• The generated file path is correct
• TypeScript path aliases are configured
• The assets directory exists

Assets Not Updating

• Run assets-gen manually to regenerate
• Check file permissions
• Use --verbose flag for detailed logs

Requirements

• Node.js: >= 18.0.0
• TypeScript: >= 5.0.0 (for consuming projects)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.

Made with ❤️ by Mukarram for the React community