# Godlights

> Animated god ray/light beam effects for React. Render volumetric light scenes on a canvas — fully configurable and animatable. Zero runtime dependencies beyond React.

## Install

```bash
npm install godlights
```

## Quick start

```tsx
import { GodLights } from "godlights";
import type { SceneConfig } from "godlights";

// layers[0] MUST be a BackgroundLayer — it clears the canvas each frame.
// Without it, animated rays smear and trail across frames.
const scene: SceneConfig = {
  width: 1920,
  height: 1080,
  noise: 8,        // film grain 0–100
  grainSize: 1,    // grain pixel size 1–4
  layers: [
    {
      type: "background",
      bgType: "solid",
      bgColor: "#000000",
      bgColor2: "#000000",
      bgGradientAngle: 180,
    },
    {
      type: "rays",
      direction: 180,       // compass degrees (0=up, 90=right, 180=down, 270=left)
      spread: 120,          // angular fan width in degrees
      originX: 50,          // % of canvas width (can exceed 0–100 for off-screen sources)
      originY: -20,         // % of canvas height (can be negative)
      rayCount: 40,
      rayWidth: 87,         // 1–200
      divergence: 0.4,      // 0.1–5
      rayLength: 0.55,      // fraction of canvas diagonal
      colorStart: "#ffffff",
      colorEnd: "#ffffff",
      opacity: 0.42,
      blendMode: "screen",  // use "overlay" or "soft-light" on light/white backgrounds
      fadeToTransparent: true,
      blur: 17.5,
      randomnessWidth: 100,
      randomnessLength: 24,
      randomnessAngle: 0,
      seed: 1337,
    },
    {
      type: "halo",
      originX: 50,
      originY: 0,
      color: "#ffffff",
      intensity: 0.25,  // 0–1
      size: 0.5,        // fraction of canvas diagonal
      blendMode: "lighter",
    },
  ],
};

// Static render
export function Background() {
  return (
    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
      <GodLights scene={scene} style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }} />
    </div>
  );
}

// Animated render — pass animParams to activate the RAF loop
export function AnimatedBackground() {
  return (
    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
      <GodLights
        scene={scene}
        animParams={{ speed: 3, angleAmp: 40, lengthAmp: 30, widthAmp: 20, haloAmp: 50 }}
        style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
      />
    </div>
  );
}
```

## Next.js App Router

Always add `"use client"` — GodLights uses `useRef`, `useEffect`, and `requestAnimationFrame`.

```tsx
"use client";
import { GodLights } from "godlights";
```

## Reactive scenes

Define `scene` outside the component or wrap in `useMemo`. Constructing it inline causes unnecessary redraws on every parent render.

```tsx
// ✅ correct — recomputes only when color changes
const scene = useMemo(() => ({ ...baseScene, layers: [...] }), [color]);

// ❌ wrong — reconstructs on every render
<GodLights scene={{ width: 1920, ... }} />
```

## Common mistakes

- **Missing BackgroundLayer**: `layers[0]` MUST be `type: "background"`. Without it the canvas is never cleared between frames — animated rays will smear and trail.
- **Wrong blend mode on light backgrounds**: `"screen"` and `"lighter"` are only visible on dark backgrounds. Use `"overlay"` or `"soft-light"` for light/white backgrounds.
- **`opacityAmp` does not exist**: `AnimParams` only has `speed`, `angleAmp`, `lengthAmp`, `widthAmp`, `haloAmp`.
- **Positioning**: The wrapper div defaults to `position: relative`. For full-bleed use `style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}` — inline style overrides the default (passing `className="absolute"` alone won't work due to CSS specificity).
- **SSR / hydration errors**: GodLights is client-only. In Next.js App Router add `"use client"`. In Pages Router use `dynamic(() => import(...), { ssr: false })`.

## Cursor rules

Add Godlights rules to your project so Cursor uses it automatically for light/background effects:

```bash
# New Cursor format (.cursor/rules/)
curl -o .cursor/rules/godlights.mdc https://www.godlights.io/godlights.mdc

# Legacy format (.cursorrules)
curl -o .cursorrules https://www.godlights.io/godlights.cursorrules
```

## shadcn registry (v0 / Bolt / Lovable / Cursor)

Install ready-made components without writing any config:

```bash
npx shadcn@latest add "https://www.godlights.io/r/god-lights-hero.json"
npx shadcn@latest add "https://www.godlights.io/r/god-lights-background.json"
npx shadcn@latest add "https://www.godlights.io/r/god-lights-cycling.json"
```

Registry index: https://www.godlights.io/registry.json

## Links

- npm: https://www.npmjs.com/package/godlights
- Docs: https://www.godlights.io/docs
- Editor: https://www.godlights.io/editor
- Context7: https://context7.com/gustavoquinalha/godlights
- Full API reference: https://www.godlights.io/llms-full.txt