🎨 Smart Image System

AI-powered image generation system for Next.js with automatic fallback to placeholders.

✨ Features

• 🤖 AI Image Generation - Generate images using WaveSpeed AI (or any AI service)
• 🎯 Centralized Configuration - Manage all images in one place
• 🔄 Automatic Fallback - Shows placeholders with prompts if images aren't generated yet
• ⚡ Type-Safe - Full TypeScript support
• 🚀 Easy to Use - Simple API, works out of the box
• 📦 Framework Agnostic - Works with any Next.js project

🚀 Quick Start

Installation

1. Copy the package to your project:

# Option 1: Download from GitHub
git clone https://github.com/yourusername/smart-image-system.git
cp -r smart-image-system/* your-project/

# Option 2: Copy files manually
# Copy lib/, components/, and scripts/ directories

2. Install dependencies:

npm install dotenv
npm install --save-dev tsx @types/node

3. Add to your package.json:

{
  "scripts": {
    "generate-images": "tsx scripts/generate-all-images.ts"
  }
}

4. Set up environment variables:

Create .env.local:

WAVESPEED_API_KEY=your_api_key_here

5. Configure your images:

Edit lib/image-mapping.ts:

export const imageMapping: ImageConfig[] = [
  {
    id: 'hero-image',
    prompt: 'Beautiful sunset over mountains, professional photography',
    path: 'public/images/hero.png',
    aspect_ratio: '16:9',
  },
];

6. Use in your components:

import SmartImage from '@/components/SmartImage';

export default function Hero() {
  return (
    <div className="relative h-screen">
      <SmartImage
        imageId="hero-image"
        alt="Hero image"
        fill
        objectFit="cover"
        priority
      />
    </div>
  );
}

7. Generate images:

npm run generate-images

📁 Project Structure

your-project/
├── lib/
│   ├── image-mapping.ts      # Image configuration
│   └── wavespeed.ts          # AI API client
├── components/
│   ├── SmartImage.tsx        # Main component
│   └── ImagePlaceholder.tsx  # Fallback placeholder
└── scripts/
    └── generate-all-images.ts # Generation script

🎯 Usage Examples

Basic Usage

<SmartImage
  imageId="product-image"
  alt="Product"
  width={800}
  height={600}
/>

Fill Container

<div className="relative h-64">
  <SmartImage
    imageId="banner-image"
    alt="Banner"
    fill
    objectFit="cover"
  />
</div>

In a Grid

{products.map(product => (
  <div key={product.id} className="relative h-64">
    <SmartImage
      imageId={`product-${product.id}`}
      alt={product.name}
      fill
      objectFit="cover"
    />
  </div>
))}

🔧 Configuration

Image Mapping

All images are configured in lib/image-mapping.ts:

export interface ImageConfig {
  id: string;              // Unique identifier
  prompt: string;          // AI generation prompt
  path: string;            // Save path (public/images/...)
  component?: string;     // Where it's used (optional)
  aspect_ratio?: '16:9' | '1:1' | '9:16' | '4:3' | '3:4';
  width?: number;
  height?: number;
}

SmartImage Props

interface SmartImageProps {
  imageId: string;        // Required: ID from image-mapping.ts
  alt: string;            // Required: Alt text
  width?: number;        // Width (if not using fill)
  height?: number;       // Height (if not using fill)
  className?: string;    // CSS classes
  priority?: boolean;    // Priority loading
  fill?: boolean;        // Fill parent container
  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
  fallback?: boolean;    // Show placeholder on error (default: true)
}

🔄 How It Works

1. Configuration - Define images in image-mapping.ts
2. Generation - Run npm run generate-images to generate all images
3. Display - Use <SmartImage> component in your code
4. Fallback - If image doesn't exist, shows placeholder with prompt
5. Optimization - Uses next/image for automatic optimization

🎨 Customization

Using Different AI Services

Replace lib/wavespeed.ts with your AI service client:

// lib/openai.ts
import OpenAI from 'openai';

export async function generateImage(prompt: string) {
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  const response = await openai.images.generate({
    model: "dall-e-3",
    prompt: prompt,
  });
  return {
    status: 'completed',
    result: { image_url: response.data[0].url },
  };
}

Then update scripts/generate-all-images.ts to use your client.

Custom Placeholder Styles

Edit components/ImagePlaceholder.tsx to match your design system.

📚 API Reference

getImagePath(id: string)

Get the public path for an image ID.

import { getImagePath } from '@/lib/image-mapping';

const path = getImagePath('hero-image'); // '/images/hero.png'

getImageConfig(id: string)

Get full configuration for an image ID.

import { getImageConfig } from '@/lib/image-mapping';

const config = getImageConfig('hero-image');

generateImage(prompt, options)

Generate a single image using WaveSpeed AI.

import { generateImage } from '@/lib/wavespeed';

const result = await generateImage('Beautiful sunset', {
  aspect_ratio: '16:9',
  output_format: 'png',
});

🐛 Troubleshooting

Images not generating

• Check WAVESPEED_API_KEY in .env.local
• Verify API key is valid
• Check API rate limits

Images not displaying

• Verify paths in image-mapping.ts start with public/
• Ensure files exist in public/images/...
• Check browser console for errors

Placeholders not showing

• Ensure fallback={true} (default)
• Verify prompt is set in image-mapping.ts

📝 License

MIT License - feel free to use in your projects!

🤝 Contributing

Contributions welcome! Please open an issue or pull request.

📧 Support

For questions or issues, please open a GitHub issue.

---

Made with ❤️ for Next.js developers