Install

One install to wrap your app

One package, no required peers besides React:

npm install @alstroemeria/iris

That's the whole integration — styles inject automatically on mount, every prop is optional, and the control panels are on by default. Keep it dev-only so production renders your app untouched:

import { Iris } from "@alstroemeria/iris";
export default function App({ children }) {
return process.env.NODE_ENV === "development"
? <Iris>{children}</Iris>
: children;
}

Next.js (App Router)

Iris uses React hooks, so the file that renders it needs client context:

// components/dev-iris.tsx
"use client";
import { Iris } from "@alstroemeria/iris";
export function DevIris({ children }: { children: React.ReactNode }) {
if (process.env.NODE_ENV !== "development") return <>{children}</>;
return <Iris>{children}</Iris>;
}
// next.config.ts
const nextConfig = {
transpilePackages: ["@alstroemeria/iris"],
};

Then wrap {children} in app/layout.tsx with <DevIris>. The library ships with a "use client" banner already — the directive above is for your wrapper file.

Vite

Same wrapper, gated on Vite's dev flag. No config changes needed:

// src/dev-iris.tsx
import { Iris } from "@alstroemeria/iris";
export function DevIris({ children }: { children: React.ReactNode }) {
if (!import.meta.env.DEV) return <>{children}</>;
return <Iris>{children}</Iris>;
}

Level up: animations & export

npm install motion modern-screenshot

Both are optional and auto-detected — no code changes:

  • motion unlocks staggered entrance reveals (auto-detects shadcn data-slot elements, or pass your own selectors via the animations prop)
  • modern-screenshot unlocks 2× PNG export (⌘⇧S)

Level up: WebGL engine

The default engine renders with pure CSS transforms and pulls zero three.js code. For true bokeh depth-of-field, focus-point falloff, and procedural 3D scene presets, opt into the WebGL engine:

npm install three @react-three/fiber @react-three/drei @react-three/postprocessing
import { Iris } from "@alstroemeria/iris";
import { WebglEngine } from "@alstroemeria/iris/three";
<Iris engines={{ webgl: WebglEngine }}>{children}</Iris>

Import WebglEngine statically (not next/dynamic) — the engine contract passes an imperative ref, which dynamic() doesn't forward. <Iris> renders nothing until client hydration, so the three.js canvas never server-renders anyway.

Peer dependencies

PackageStatusEnables
react, react-dom ≥ 18required—
motion ≥ 12optionalentrance animations
modern-screenshot ≥ 4optionalscreenshot export
three ≥ 0.184, @react-three/fiber ≥ 9, @react-three/drei ≥ 10, @react-three/postprocessing ≥ 3optionalWebGL engine (@alstroemeria/iris/three)

Only React is needed for the default CSS engine — the optional peers are detected at runtime. Styles are injected as a <style> tag on mount; if your CSP disallows that, import @alstroemeria/iris/styles.css instead.