assets-ai

React components designed for AI agents to fetch media assets using natural language descriptions. Built to simplify media integration in AI-powered applications by allowing agents to request icons, images, and videos with simple text descriptions instead of managing file paths and asset libraries.

Why assets-ai?

Traditional asset management requires developers and AI agents to know exact file names, manage asset libraries, and handle complex path structures. assets-ai solves this by letting AI agents fetch any media using natural language descriptions:

// Instead of: <Icon src="/icons/home-regular.svg" />
<Icon description="home" variant="regular" />

// Instead of: <img src="/images/sunset-mountain-landscape-4k.jpg" />
<Image description="sunset over mountains" />

Perfect for AI-powered applications where agents generate UIs dynamically and need media without pre-configured asset catalogs.

Installation

npm install assets-ai

Quick Start

1. Configure and Wrap Your App

Set up the MediaProvider in your root layout or app file:

import { configureMedia, MediaProvider } from 'assets-ai';

// Configure the media system
configureMedia({
  apiEndpoint: "https://api.oblien.com/icons/fetch",
  apiToken: process.env.NEXT_PUBLIC_OBLIEN_TOKEN,
  manifestUrl: "/media-manifest.json",
  maxCacheSize: 2 * 1024 * 1024, // 2MB
  staticBaseUrls: {
    icon: "https://cdn.oblien.com/icons/",
    image: "https://cdn.oblien.com/images/",
    video: "https://cdn.oblien.com/videos/",
  },
});

export default function App({ children }) {
  return (
    <MediaProvider 
      batchDelay={500}
      maxCacheSize={2 * 1024 * 1024}
    >
      {children}
    </MediaProvider>
  );
}

2. Use Components

AI agents can now fetch media using simple descriptions:

import { Icon, Image, Video } from 'assets-ai';

function MyComponent() {
  return (
    <div>
      {/* AI agent requests icon by description */}
      <Icon 
        description="home" 
        variant="regular" 
        size={24} 
        color="#000"
        fallback={true}
      />

      {/* AI agent requests image by description */}
      <Image 
        description="sunset over mountains"
        width={400}
        height={300}
        alt="Beautiful sunset"
        fallback={true}
      />

      {/* Optional: Static assets for known files */}
      <Icon name="logo.svg" size={32} />

      {/* AI agent requests video by description */}
      <Video
        description="ocean waves"
        controls={true}
        width={640}
        height={360}
        fallback={true}
      />
    </div>
  );
}

Components

Icon

Render icons with multiple style variants.

Props:

• description (string): AI prompt for generating the icon
• name (string): Static icon filename (bypasses AI)
• variant (string): Icon style - "regular" | "bold" | "light" | "broken" | "two-tone" | "outline"
• size (number | string): Icon size in pixels
• color (string): Icon color (CSS color value)
• className (string): Additional CSS classes
• style (CSSProperties): Inline styles
• fallback (boolean | ReactNode): Show skeleton loader or custom fallback
• alt (string): Alternative text for accessibility

Image

Render AI-generated or static images.

Props:

• description (string): AI prompt for generating the image
• name (string): Static image filename (bypasses AI)
• width (number | string): Image width
• height (number | string): Image height
• alt (string): Alternative text
• className (string): Additional CSS classes
• fallback (boolean | ReactNode): Show skeleton loader or custom fallback

Video

Render AI-generated or static videos.

Props:

• description (string): AI prompt for generating the video
• name (string): Static video filename (bypasses AI)
• width (number | string): Video width
• height (number | string): Video height
• controls (boolean): Show video controls (default: true)
• autoPlay (boolean): Auto-play video
• loop (boolean): Loop video
• muted (boolean): Mute audio
• className (string): Additional CSS classes
• fallback (boolean | ReactNode): Show skeleton loader or custom fallback

Configuration

configureMedia(config)

Configure the media system globally before rendering your app.

Options:

• apiEndpoint (string): API endpoint for fetching media
• apiToken (string): Authentication token
• manifestUrl (string): URL to production manifest file
• maxCacheSize (number): Maximum cache size in bytes
• staticBaseUrls (object): Base URLs for static assets
  • icon (string): Base URL for icons
  • image (string): Base URL for images
  • video (string): Base URL for videos

MediaProvider

Context provider that manages media fetching, caching, and state.

Props:

• batchDelay (number): Milliseconds to wait before batching requests (default: 500)
• maxCacheSize (number): Maximum cache size in bytes (default: 1MB)

Features

Description-Based Media Fetching

AI agents can request any media asset using natural language descriptions without knowing file names or managing asset libraries. Simply describe what you need and the system handles the rest.

Intelligent Batching

Multiple media requests are automatically batched together to reduce API calls and improve performance. Critical for AI agents making numerous media requests.

Local Caching

Media URLs are cached in localStorage during development to speed up subsequent page loads and reduce API usage. AI agents benefit from instant access to previously fetched assets.

Production Manifests

In production, media URLs are loaded from a static manifest file for optimal performance and reduced runtime overhead.

Loading States

Built-in skeleton loaders and customizable fallbacks provide smooth loading experiences while assets are being fetched.

Static Assets

Optional support for static assets using the name prop when you need to serve pre-existing files from your CDN.

API

clearMediaCache()

Clear all cached media URLs from localStorage.

import { clearMediaCache } from 'assets-ai';

clearMediaCache();

useMediaContext()

Access the media context directly in your components.

import { useMediaContext } from 'assets-ai';

function MyComponent() {
  const { mediaMap, registerMedia, isItemLoading, getStaticUrl } = useMediaContext();
  
  // Your component logic
}

Environment Modes

Development Mode

• Media requests are sent to the API
• URLs are cached in localStorage
• Batch requests are debounced

Production Mode

• Media URLs are loaded from a static manifest file
• No API requests are made at runtime
• No localStorage caching

Documentation

For complete documentation, examples, and API reference, visit:

https://oblien.com/docs/assets

License

MIT

Repository

https://github.com/oblien/assets-ai