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.tsconst 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.tsximport { 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-slotelements, or pass your own selectors via theanimationsprop) - 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
| Package | Status | Enables |
|---|---|---|
react, react-dom ≥ 18 | required | — |
motion ≥ 12 | optional | entrance animations |
modern-screenshot ≥ 4 | optional | screenshot export |
three ≥ 0.184, @react-three/fiber ≥ 9, @react-three/drei ≥ 10, @react-three/postprocessing ≥ 3 | optional | WebGL 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.