@with-logic/magic-image

AI-powered image generation with an in-browser dev overlay for React.

Generate, preview, and save AI images directly in your development environment. Perfect for rapidly iterating on content imagery during development.

Installation

npm install @with-logic/magic-image

For the built-in Replicate generator:

npm install replicate

Quick Start

import {
  MagicImage,
  MagicImageProvider,
  createBrowserDownloadSaver,
} from "@with-logic/magic-image";
import { createReplicateGenerator } from "@with-logic/magic-image/replicate";
import "@with-logic/magic-image/styles.css";

const generateImage = createReplicateGenerator({
  apiKey: import.meta.env.VITE_REPLICATE_API_KEY,
});

const saveImage = createBrowserDownloadSaver();

function App() {
  return (
    <MagicImageProvider
      devMode={import.meta.env.DEV}
      generateImage={generateImage}
      saveImage={saveImage}
    >
      <MagicImage
        src="/images/hero.jpg"
        alt="Hero image"
        prompt="A minimalist illustration of a modern workspace"
        aspectRatio="16:9"
      />
    </MagicImageProvider>
  );
}

API Reference

MagicImage

The main component that displays images and provides the dev overlay for generation.

<MagicImage
  src="/images/hero.jpg"
  alt="Hero image"
  prompt="A minimalist illustration of a modern workspace"
  aspectRatio="16:9"
  devMode={true}
/>

Prop	Type	Required	Description
src	string	Yes	Path to the image (used for display and as save target)
alt	string	Yes	Alt text for accessibility
prompt	string	No	Prompt for image generation (required for overlay to appear)
aspectRatio	"4:3" | "16:9"	No	Aspect ratio for generated images. Default: "4:3"
devMode	boolean	No	Override provider's devMode for this specific image

All standard <img> props are also supported.

MagicImageProvider

Provider component that supplies configuration to all MagicImage components.

<MagicImageProvider
  devMode={process.env.NODE_ENV === "development"}
  generateImage={generateImage}
  saveImage={saveImage}
  refinePrompt={refinePrompt}
>
  <App />
</MagicImageProvider>

Prop	Type	Required	Description
devMode	boolean	No	Enables the generation overlay. Default: false
generateImage	GenerateImageHandler	Yes	Function that generates images from prompts
saveImage	SaveImageHandler	Yes	Function that saves/downloads images
refinePrompt	RefinePromptHandler	No	Optional function to enhance prompts before generation

Hooks

useMagicImage

Returns the MagicImage configuration. Throws if used outside a provider.

import { useMagicImage } from "@with-logic/magic-image";

function MyComponent() {
  const { generateImage, saveImage, devMode } = useMagicImage();
  // ...
}

useMagicImageConfig

Returns the MagicImage configuration or undefined if outside a provider.

import { useMagicImageConfig } from "@with-logic/magic-image";

function MyComponent() {
  const config = useMagicImageConfig();
  if (!config) {
    return <div>Not in provider</div>;
  }
  // ...
}

Generators

createReplicateGenerator

Creates an image generator using Replicate's API with FLUX as the default model.

import { createReplicateGenerator } from "@with-logic/magic-image/replicate";

const generateImage = createReplicateGenerator({
  apiKey: process.env.REPLICATE_API_KEY!,
  model: "black-forest-labs/flux-schnell", // optional
});

Option	Type	Required	Description
apiKey	string	Yes	Your Replicate API key
model	string	No	Model identifier. Default: "black-forest-labs/flux-schnell"

Savers

createBrowserDownloadSaver

Creates a save handler that triggers the browser's native download dialog.

import { createBrowserDownloadSaver } from "@with-logic/magic-image";

const saveImage = createBrowserDownloadSaver({
  getFilename: (targetPath) => targetPath.split("/").pop() ?? "image.png",
});

Option	Type	Required	Description
getFilename	(targetPath: string) => string	No	Custom function to derive filename from path

Custom Handlers

You can implement custom generate and save handlers:

// Custom generate handler
const generateImage: GenerateImageHandler = async ({
  prompt,
  aspectRatio,
  referenceImage,
}) => {
  const response = await fetch("/api/generate-image", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt, aspectRatio, referenceImage }),
  });
  return response.json(); // Must return { imageUrl: string }
};

// Custom save handler
const saveImage: SaveImageHandler = async ({ imageData, targetPath }) => {
  const response = await fetch("/api/save-image", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ imageData, targetPath }),
  });
  return response.json(); // Must return { success: boolean, savedPath?: string }
};

// Optional prompt refinement
const refinePrompt: RefinePromptHandler = async (prompt) => {
  const response = await fetch("/api/refine-prompt", {
    method: "POST",
    body: JSON.stringify({ prompt }),
  });
  const { refinedPrompt } = await response.json();
  return refinedPrompt;
};

Types

import type {
  MagicImageProps,
  MagicImageConfig,
  GenerateImageHandler,
  SaveImageHandler,
  RefinePromptHandler,
  ImageState,
} from "@with-logic/magic-image";

Integration Guides

• Plain React / Vite
• React Router
• Next.js

License

MIT