Auraimage React

AuraImage React Components

Guidelines for using the AuraImage Shadcn component registry — the recommended way to display and upload images in React and Next.js projects.

When to Apply

Use these guidelines instead of (or alongside) auraimage-url-api when:

• The project uses React or Next.js.
• You need image display with built-in BlurHash placeholders.
• You need an upload UI component (<AuraUploader />).
• You want zero-boilerplate LCP optimization.

Installing Components

Components are copied directly into your /components folder — no locked NPM package, full code ownership:

# Display component (recommended for all image rendering)
npx shadcn@latest add https://auraimage.ai/registry/image.json

# Upload widget (drag-and-drop + presigned upload)
npx shadcn@latest add https://auraimage.ai/registry/uploader.json

Both components read the CDN base URL from NEXT_PUBLIC_AURA_CDN_URL.

Rule Categories

1. Display: <AuraImage /> (CRITICAL)

• prefer-aura-image — In React projects, always use <AuraImage /> instead of raw <picture> or <img>. It implements the placeholder → full-image fade automatically.
• aura-image-lcp — Set priority on the above-the-fold image to trigger preloading.

2. Upload: <AuraUploader /> (HIGH)

• prefer-aura-uploader — Use <AuraUploader /> for any image upload UI. It handles signature fetching, client-side preview, progress, retries, and direct-to-edge upload.
• uploader-server-route — Wire <AuraUploader /> to a server route at /api/aura/sign that calls aura.signUpload().

3. Placeholder loading (HIGH)

• placeholder-loading — Understand the placeholder strategies (blurhash, lqip, empty) so you can configure them correctly per use case.

<AuraImage /> usage

src is a single string in extension-less projectName/name form (e.g. my-app/hero, no file extension) — the component builds the path-based CDN URL from it.

Basic

import { AuraImage } from '@/components/aura/image';

<AuraImage
  src='my-app/hero'
  alt='Hero image'
  width={1200}
  height={800}
/>

LCP / hero image

<AuraImage
  src='my-app/hero'
  alt='Hero'
  width={1200}
  height={800}
  priority           // preloads + fetchpriority="high"
  placeholder='blurhash'
/>

The component fetches the BlurHash automatically — there is no blurhash prop. Persist the value returned by signUpload's upload response if you want to inspect it elsewhere, but the component does not require it.

Thumbnail with face crop

<AuraImage
  src='my-app/avatar'
  alt='User avatar'
  width={80}
  height={80}
  fit='face'
  quality={90}
/>

Skipping BlurHash

<AuraImage
  src='my-app/photo'
  alt='Photo'
  width={800}
  height={600}
  placeholder='lqip'  // skip blurhash, fetch a 50px low-quality preview directly
/>

Placeholder loading

The component renders the chosen placeholder, then crossfades the full image in once it loads:

placeholder='empty' skips the placeholder entirely.

<AuraUploader /> usage

import { AuraUploader } from '@/components/aura/uploader';

export default function ProfilePage() {
  return (
    <AuraUploader
      project='my-app'
      => {
        // result.url    — canonical extension-less CDN URL
        // result.name   — extension-less name; pass to getSignedUrl() / setVisibility()
        // result.blurhash — store for placeholder rendering
        console.log('Uploaded:', result.url);
      }}
      accept='image/*'
      maxSize='5mb'
    />
  );
}

Server-side signature endpoint

The project prop tells the uploader to POST to /api/aura/sign and expect { signature } back:

import { AuraImage } from '@auraimage/sdk';

const aura = new AuraImage({
  secretKey: process.env.AURA_SECRET_KEY!,
  projectName: process.env.NEXT_PUBLIC_AURA_PROJECT_NAME!
});

export async function POST() {
  const signature = await aura.signUpload({
    maxSize: '5mb',
    allowedTypes: ['image/*'],
    expiresIn: 3600
  });
  return Response.json({ signature });
}

For RSC-minted signatures or custom auth flows, pass signature (string) or getSignature (async function) instead of project.

How to use

Read individual rule files for detailed explanations and code examples:

rules/prefer-aura-image.md
rules/placeholder-loading.md
rules/aura-uploader.md