Configuration

Learn how to configure Assets AI for optimal performance in development and production environments.

Global Configuration

Use configureMedia() to set up global configuration before your app renders. This should be called once in your root layout or app file.

import { configureMedia } from 'assets-ai';

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

Configuration Options

apiEndpoint

Type: string
Required: Yes
Default: "https://api.oblien.com/icons/fetch"

The API endpoint for fetching media assets. This is where requests are sent in development mode.

configureMedia({
  apiEndpoint: "https://api.oblien.com/icons/fetch",
});

apiToken

Type: string
Required: Yes
Default: ""

Your Oblien API token for authentication. Get your token from oblien.com.

configureMedia({
  apiToken: process.env.NEXT_PUBLIC_OBLIEN_TOKEN,
});

Security Best Practice: Always use environment variables for API tokens.

.env.local

NEXT_PUBLIC_OBLIEN_TOKEN=your_token_here

manifestUrl

Type: string
Required: No
Default: "/media-manifest.json"

The URL to your production manifest file. In production, Assets AI loads all media URLs from this manifest instead of making API requests.

configureMedia({
  manifestUrl: "/media-manifest.json",
});

maxCacheSize

Type: number
Required: No
Default: 1048576 (1MB)

Maximum size in bytes for the localStorage cache. When exceeded, the cache is cleared automatically.

configureMedia({
  maxCacheSize: 2 * 1024 * 1024, // 2MB
});

staticBaseUrls

Type: object
Required: No
Default: Oblien CDN URLs

Base URLs for serving static assets without AI generation. Used when components have a name prop instead of description.

configureMedia({
  staticBaseUrls: {
    icon: "https://cdn.oblien.com/icons/",
    image: "https://cdn.oblien.com/images/",
    video: "https://cdn.oblien.com/videos/",
  },
});

You can also use your own CDN:

configureMedia({
  staticBaseUrls: {
    icon: "https://cdn.yourcompany.com/icons/",
    image: "https://cdn.yourcompany.com/images/",
    video: "https://cdn.yourcompany.com/videos/",
  },
});

MediaProvider Props

The MediaProvider component wraps your application and manages media state.

<MediaProvider batchDelay={500} maxCacheSize={2 * 1024 * 1024}>
  {children}
</MediaProvider>

batchDelay

Type: number
Required: No
Default: 500

Milliseconds to wait before batching media requests. Higher values batch more requests together but increase initial loading time.

<MediaProvider batchDelay={300}>
  {children}
</MediaProvider>

Recommended values:

Fast UI: 300-400ms
Balanced: 500ms (default)
Maximum batching: 800-1000ms

maxCacheSize

Type: number
Required: No
Default: 1048576 (1MB)

Maximum size in bytes for localStorage cache. Should match the global config.

<MediaProvider maxCacheSize={2 * 1024 * 1024}>
  {children}
</MediaProvider>

Environment-Specific Configuration

Development Configuration

app/layout.tsx

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

configureMedia({
  apiEndpoint: "https://api.oblien.com/icons/fetch",
  apiToken: process.env.NEXT_PUBLIC_OBLIEN_TOKEN,
  maxCacheSize: 5 * 1024 * 1024, // 5MB for development
});

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <MediaProvider batchDelay={500}>
          {children}
        </MediaProvider>
      </body>
    </html>
  );
}

Production Configuration

app/layout.tsx

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

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

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <MediaProvider batchDelay={500}>
          {children}
        </MediaProvider>
      </body>
    </html>
  );
}

Cache Management

Clear Cache Programmatically

import { clearMediaCache } from 'assets-ai';

function SettingsPage() {
  const handleClearCache = () => {
    clearMediaCache();
    alert('Cache cleared!');
  };

  return (
    <button onClick={handleClearCache}>
      Clear Media Cache
    </button>
  );
}

Cache Behavior

Development Mode:

Media URLs are cached in localStorage
Cache persists across page reloads
Automatically cleared if size exceeds maxCacheSize

Production Mode:

No localStorage caching (uses manifest instead)
All URLs loaded from static manifest file
No runtime API requests

Framework-Specific Setup

Next.js App Router

app/layout.tsx

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

configureMedia({
  apiToken: process.env.NEXT_PUBLIC_OBLIEN_TOKEN,
});

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <MediaProvider>
          {children}
        </MediaProvider>
      </body>
    </html>
  );
}

Next.js Pages Router

pages/_app.tsx

import { configureMedia, MediaProvider } from 'assets-ai';
import type { AppProps } from 'next/app';

configureMedia({
  apiToken: process.env.NEXT_PUBLIC_OBLIEN_TOKEN,
});

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MediaProvider>
      <Component {...pageProps} />
    </MediaProvider>
  );
}

React (Vite, CRA)

main.tsx

import { configureMedia, MediaProvider } from 'assets-ai';
import ReactDOM from 'react-dom/client';
import App from './App';

configureMedia({
  apiToken: import.meta.env.VITE_OBLIEN_TOKEN,
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <MediaProvider>
    <App />
  </MediaProvider>
);

Remix

app/root.tsx

import { configureMedia, MediaProvider } from 'assets-ai';
import { Outlet } from '@remix-run/react';

configureMedia({
  apiToken: process.env.OBLIEN_TOKEN,
});

export default function Root() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
      </head>
      <body>
        <MediaProvider>
          <Outlet />
        </MediaProvider>
      </body>
    </html>
  );
}

TypeScript Configuration

Assets AI includes full TypeScript support out of the box. No additional configuration needed.

import type { 
  MediaType, 
  MediaMap, 
  MediaRequest 
} from 'assets-ai';

const mediaType: MediaType = "icon";
const mediaMap: MediaMap = { "icon:home:regular": "https://..." };

Performance Optimization

Batch Delay Tuning

Adjust batch delay based on your use case:

// Fast initial render, fewer batched requests
<MediaProvider batchDelay={200}>

// Balanced
<MediaProvider batchDelay={500}>

// Maximum batching, slight delay
<MediaProvider batchDelay={1000}>

Cache Size Tuning

Set cache size based on your needs:

// Small apps
maxCacheSize: 1 * 1024 * 1024  // 1MB

// Medium apps
maxCacheSize: 2 * 1024 * 1024  // 2MB

// Large apps
maxCacheSize: 5 * 1024 * 1024  // 5MB

Production Manifest

For production, generate a manifest file containing all media URLs to eliminate runtime API requests:

public/media-manifest.json

{
  "icon:home:regular": "https://cdn.oblien.com/icons/home-regular.svg",
  "icon:search:regular": "https://cdn.oblien.com/icons/search-regular.svg",
  "image:sunset": "https://cdn.oblien.com/images/sunset-mountains.jpg"
}

Troubleshooting

API Requests Not Working

Check that your API token is correctly set:

console.log(process.env.NEXT_PUBLIC_OBLIEN_TOKEN); // Should not be undefined

Cache Not Persisting

Ensure localStorage is available:

if (typeof window !== 'undefined' && window.localStorage) {
  console.log('localStorage is available');
}

Large Cache Size

Monitor cache size and adjust maxCacheSize:

const cacheData = localStorage.getItem('oblien_media_cache');
const size = cacheData ? new Blob([cacheData]).size : 0;
console.log(`Cache size: ${(size / 1024).toFixed(2)}KB`);

On this page