React Integration Guide

This guide covers best practices for integrating Fuderu with React applications, including hooks, lifecycle management, and performance optimization.

Basic Setup

Installation

npm install fuderu
# or
yarn add fuderu

Basic Usage

import React, { useEffect, useRef } from "react";
import { Canvas } from "fuderu";

function DrawingCanvas() {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    if (!canvasRef.current) return;

    const painter = new Canvas({
      canvas: canvasRef.current,
      document: {
        width: 800,
        height: 600,
      },
    });

    // Cleanup on unmount
    return () => {
      painter.destroy();
    };
  }, []);

  return <canvas ref={canvasRef} width={800} height={600} />;
}

Custom Hooks

useFuderuCanvas Hook

Create a reusable hook for canvas management:

import { useEffect, useRef } from "react";
import { Canvas, Brush } from "fuderu";

interface UseFuderuCanvasOptions {
  width?: number;
  height?: number;
  brushConfig?: Partial<Brush.BrushConfig>;
  onReady?: (painter: Canvas) => void;
}

export function useFuderuCanvas({
  width = 800,
  height = 600,
  brushConfig,
  onReady,
}: UseFuderuCanvasOptions = {}) {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const painterRef = useRef<Canvas | null>(null);

  useEffect(() => {
    if (!canvasRef.current) return;

    const painter = new Canvas({
      canvas: canvasRef.current,
      document: { width, height },
      brush: brushConfig,
    });

    painterRef.current = painter;
    onReady?.(painter);

    return () => {
      painter.destroy();
      painterRef.current = null;
    };
  }, [width, height, brushConfig, onReady]);

  return canvasRef;
}

Advanced Hook with Brush Controls

import { useState, useCallback } from "react";
import { Canvas, Brush } from "fuderu";

export function useDrawingCanvas(
  initialOptions: {
    width?: number;
    height?: number;
    brushConfig?: Partial<Brush.BrushConfig>;
  } = {},
) {
  const [canvasRef, setCanvasRef] =
    useState<React.RefObject<HTMLCanvasElement> | null>(null);
  const [painter, setPainter] = useState<Canvas | null>(null);
  const [brushConfig, setBrushConfig] = useState<Brush.BrushConfig>({
    size: 20,
    color: "#000000",
    opacity: 1,
    flow: 1,
    ...(initialOptions.brushConfig || {}),
  });

  // Initialize canvas
  useEffect(() => {
    if (!canvasRef?.current) return;

    const newPainter = new Canvas({
      canvas: canvasRef.current,
      document: {
        width: initialOptions.width ?? 800,
        height: initialOptions.height ?? 600,
      },
      brush: brushConfig,
    });

    setPainter(newPainter);

    return () => {
      newPainter.destroy();
    };
  }, [canvasRef, initialOptions.width, initialOptions.height, brushConfig]);

  // Brush control functions
  const setBrushColor = useCallback(
    (color: string) => {
      setBrushConfig((prev) => ({ ...prev, color }));
      if (painter) {
        painter.brush.config.color = color;
      }
    },
    [painter],
  );

  const setBrushSize = useCallback(
    (size: number) => {
      setBrushConfig((prev) => ({ ...prev, size }));
      if (painter) {
        painter.brush.config.size = size;
      }
    },
    [painter],
  );

  const setBrushOpacity = useCallback(
    (opacity: number) => {
      setBrushConfig((prev) => ({ ...prev, opacity }));
      if (painter) {
        painter.brush.config.opacity = opacity;
      }
    },
    [painter],
  );

  const clearCanvas = useCallback(() => {
    if (painter) {
      painter.clear();
    }
  }, [painter]);

  const undo = useCallback(() => {
    if (painter) {
      painter.undo();
    }
  }, [painter]);

  const redo = useCallback(() => {
    if (painter) {
      painter.redo();
    }
  }, [painter]);

  return {
    canvasRef,
    setCanvasRef,
    painter,
    brushConfig,
    setBrushColor,
    setBrushSize,
    setBrushOpacity,
    clearCanvas,
    undo,
    redo,
    setBrushConfig, // Direct setter for advanced use
  };
}

Component Patterns

Drawing Toolbar Component

import { useState } from "react";

function DrawingToolbar({
  onBrushChange,
}: {
  onBrushChange: (config: Partial<Brush.BrushConfig>) => void;
}) {
  const [color, setColor] = useState("#000000");
  const [size, setSize] = useState(20);
  const [opacity, setOpacity] = useState(1);
  const [isEraser, setIsEraser] = useState(false);

  return (
    <div className="toolbar">
      <div className="toolbar-group">
        <label>Color:</label>
        <input
          type="color"
          value={color}
          onChange={(e) => {
            setColor(e.target.value);
            onBrushChange({ color: e.target.value });
          }}
        />
      </div>

      <div className="toolbar-group">
        <label>Size:</label>
        <input
          type="range"
          min={1}
          max={100}
          value={size}
          onChange={(e) => {
            setSize(Number(e.target.value));
            onBrushChange({ size: Number(e.target.value) });
          }}
        />
        <span>{size}px</span>
      </div>

      <div className="toolbar-group">
        <label>Opacity:</label>
        <input
          type="range"
          min={0}
          max={1}
          step={0.01}
          value={opacity}
          onChange={(e) => {
            setOpacity(Number(e.target.value));
            onBrushChange({ opacity: Number(e.target.value) });
          }}
        />
        <span>{(opacity * 100).toFixed(0)}%</span>
      </div>

      <div className="toolbar-group">
        <label>
          <input
            type="checkbox"
            checked={isEraser}
            onChange={(e) => {
              setIsEraser(e.target.checked);
              onBrushChange({ eraser: e.target.checked });
            }}
          />
          Eraser
        </label>
      </div>
    </div>
  );
}

Layer Panel Component

import { useState } from "react";
import type { BlendMode } from "fuderu";

interface LayerProps {
  onSelectLayer: (layerId: string) => void;
  onUpdateLayer: (
    layerId: string,
    options: Partial<{
      name: string;
      visible: boolean;
      opacity: number;
      blendMode: BlendMode;
    }>,
  ) => void;
  onAddLayer: () => void;
  onRemoveLayer: (layerId: string) => void;
  layers: Array<{
    id: string;
    name: string;
    visible: boolean;
    opacity: number;
    blendMode: BlendMode;
  }>;
  activeLayerId: string | null;
}

function LayerPanel({
  layers,
  activeLayerId,
  onSelectLayer,
  onUpdateLayer,
  onAddLayer,
  onRemoveLayer,
}: LayerProps) {
  return (
    <div className="layer-panel">
      <h3>Layers</h3>
      <button onClick={onAddLayer}>+ Add Layer</button>

      <div className="layer-list">
        {layers.map((layer) => (
          <div
            key={layer.id}
            className={`layer-item ${layer.id === activeLayerId ? "active" : ""}`}
            onClick={() => onSelectLayer(layer.id)}
          >
            <div className="layer-controls">
              <input
                type="checkbox"
                checked={layer.visible}
                onChange={(e) => {
                  onUpdateLayer(layer.id, { visible: e.target.checked });
                }}
              />
              <input
                type="text"
                value={layer.name}
                onChange={(e) => {
                  onUpdateLayer(layer.id, { name: e.target.value });
                }}
                placeholder="Layer name"
              />
            </div>

            <div className="layer-properties">
              <div>
                <label>Opacity:</label>
                <input
                  type="range"
                  min={0}
                  max={1}
                  step={0.01}
                  value={layer.opacity}
                  onChange={(e) => {
                    onUpdateLayer(layer.id, {
                      opacity: Number(e.target.value),
                    });
                  }}
                />
              </div>

              <div>
                <label>Blend Mode:</label>
                <select
                  value={layer.blendMode}
                  onChange={(e) => {
                    onUpdateLayer(layer.id, {
                      blendMode: e.target.value as ImportMeta["BlendMode"],
                    });
                  }}
                >
                  <option value="source-over">Normal</option>
                  <option value="multiply">Multiply</option>
                  <option value="screen">Screen</option>
                  <option value="overlay">Overlay</option>
                  {/* Add more blend modes as needed */}
                </select>
              </div>
            </div>

            <button
              onClick={(e) => {
                e.stopPropagation(); // Prevent layer selection
                onRemoveLayer(layer.id);
              }}
              className="remove-layer"
            >
              ×
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

Performance Optimization in React

Preventing Unnecessary Renders

import { useMemo, useCallback } from "react";
import { Canvas } from "fuderu";

function OptimizedDrawingCanvas() {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  // Memoize expensive configurations
  const brushConfig = useMemo(
    () => ({
      size: 24,
      color: "#ff6b6b",
      opacity: 0.8,
      flow: 0.9,
      spacing: 0.2,
    }),
    [],
  ); // Empty deps = never change

  useEffect(() => {
    if (!canvasRef.current) return;

    const painter = new Canvas({
      canvas: canvasRef.current,
      brush: brushConfig,
    });

    return () => painter.destroy();
  }, [canvasRef, brushConfig]); // Only recreate when brushConfig changes

  return <canvas ref={canvasRef} width={800} height={600} />;
}

Debouncing Rapid Updates

import { useState, useEffect, useRef } from "react";
import { Canvas } from "fuderu";

function DebouncedBrushControls() {
  const [brushConfig, setBrushConfig] = useState({
    size: 20,
    color: "#000000",
  });
  const [debouncedConfig, setDebouncedConfig] = useState(brushConfig);
  const timeoutRef = useRef<number | null>(null);

  // Debounce config changes
  useEffect(() => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }

    timeoutRef.current = window.setTimeout(() => {
      setDebouncedConfig(brushConfig);
    }, 100); // 100ms debounce

    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, [brushConfig]);

  // Apply debounced config to canvas
  useEffect(() => {
    // ... canvas setup with debouncedConfig
  }, [debouncedConfig]);

  return (
    <div>
      {/* Controls that update brushConfig (not debounced) */}
      <input
        type="range"
        min={1}
        max={100}
        value={brushConfig.size}
        onChange={(e) =>
          setBrushConfig({ ...brushConfig, size: Number(e.target.value) })
        }
      />
      {/* ... other controls */}
    </div>
  );
}

Virtualizing Large Canvases

For applications that need to support very large virtual canvases:

import { useState, useEffect } from "react";
import { Canvas } from "fuderu";

function VirtualCanvas({
  virtualWidth,
  virtualHeight,
  viewWidth,
  viewHeight,
}: {
  virtualWidth: number;
  virtualHeight: number;
  viewWidth: number;
  viewHeight: number;
}) {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [offset, setOffset] = useState({ x: 0, y: 0 });

  useEffect(() => {
    if (!canvasRef.current) return;

    // Create canvas at view size, not virtual size
    const painter = new Canvas({
      canvas: canvasRef.current,
      document: { width: viewWidth, height: viewHeight },
    });

    // Implement panning logic here
    // ...

    return () => painter.destroy();
  }, [canvasRef, viewWidth, viewHeight]);

  return (
    <div
      style={{
        width: `${viewWidth}px`,
        height: `${viewHeight}px`,
        overflow: "hidden",
        position: "relative",
      }}
      onWheel={(e) => {
        // Handle panning with mouse wheel
        e.preventDefault();
        setOffset((prev) => ({
          x: Math.max(0, Math.min(virtualWidth - viewWidth, prev.x + e.deltaY)),
          y: Math.max(
            0,
            Math.min(virtualHeight - viewHeight, prev.y + e.deltaX),
          ),
        }));
      }}
    >
      <canvas ref={canvasRef} width={viewWidth} height={viewHeight} />
    </div>
  );
}

Handling React Specific Issues

Strict Mode and Double Execution

In React 18's Strict Mode, effects may run twice in development:

useEffect(() => {
  if (!canvasRef.current) return;

  let painter: Canvas | null = null;

  // Initialize only once
  if (!painter) {
    painter = new Canvas({
      canvas: canvasRef.current,
      // ... options
    });
  }

  return () => {
    // Cleanup only runs once per actual unmount
    if (painter) {
      painter.destroy();
      painter = null;
    }
  };
}, []); // Empty deps - runs on mount/unmount

Concurrent Mode Considerations

For React Concurrent Mode, ensure your integration is interrupt-safe:

function SafeDrawingCanvas() {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [isInitialized, setIsInitialized] = useState(false);

  useEffect(() => {
    if (!canvasRef.current || isInitialized) return;

    const painter = new Canvas({
      canvas: canvasRef.current,
      // ... options
    });

    setIsInitialized(true);

    return () => {
      if (isInitialized) {
        painter.destroy();
      }
    };
  }, [canvasRef.current, isInitialized]); // Re-run if canvas changes or initialization state changes

  return <canvas ref={canvasRef} width={800} height={600} />;
}

Server-Side Rendering (SSR) Considerations

Next.js Example

import { useEffect, useRef } from "react";
import dynamic from "next/dynamic";

// Dynamically import to prevent SSR issues
const DrawingCanvas = dynamic(() => import("./DrawingCanvas"), {
  ssr: false, // Disable SSR since canvas requires browser
});

export default function Page() {
  return (
    <div>
      <h1>Drawing App</h1>
      <DrawingCanvas />
    </div>
  );
}

Creating a Placeholder for SSR

import { useEffect, useRef } from "react";

function DrawingCanvasSSR() {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    if (typeof window === "undefined") return; // Skip during SSR

    if (!canvasRef.current) return;

    const painter = new Canvas({
      canvas: canvasRef.current,
      // ... options
    });

    return () => painter.destroy();
  }, []);

  // Show placeholder during SSR
  if (typeof window === "undefined") {
    return <div className="canvas-placeholder">Drawing Canvas</div>;
  }

  return <canvas ref={canvasRef} width={800} height={600} />;
}

Advanced Integration Patterns

Context-Based State Management

import { createContext, useContext, useState } from "react";
import { Canvas } from "fuderu";

const DrawingContext = createContext({
  painter: null,
  setBrushConfig: () => {},
  clearCanvas: () => {},
  // ... other actions
});

export function useDrawing() {
  return useContext(DrawingContext);
}

export function DrawingProvider({ children }: { children: React.ReactNode }) {
  const [painter, setPainter] = useState<Canvas | null>(null);

  const setBrushConfig = useCallback(
    (config: Partial<Brush.BrushConfig>) => {
      if (painter) {
        Object.assign(painter.brush.config, config);
      }
    },
    [painter],
  );

  const clearCanvas = useCallback(() => {
    if (painter) {
      painter.clear();
    }
  }, [painter]);

  return (
    <DrawingContext.Provider
      value={{
        painter,
        setBrushConfig,
        clearCanvas,
        // ... other values
      }}
    >
      {children}
    </DrawingContext.Provider>
  );
}

Integration with State Management Libraries

Redux Example

// actions.ts
export const setBrushSize = (size: number) => ({
  type: "BRUSH_SET_SIZE",
  payload: size
});

export const setBrushColor = (color: string) => ({
  type: "BRUSH_SET_COLOR",
  payload: color
});

// reducer.ts
const initialState = {
  brushSize: 20,
  brushColor: "#000000"
};

function brushReducer(state = initialState, action) {
  switch (action.type) {
    case "BRUSH_SET_SIZE":
      return { ...state, brushSize: action.payload };
    case "BRUSH_SET_COLOR":
      return { ...state, brushColor: action.payload };
    default:
      return state;
  }
}

// component.ts
import { useDispatch, useSelector } from "react-redux";
import { useEffect, useRef } from "react";
import { Canvas } from "fuderu";

function DrawingCanvas() {
  const dispatch = useDispatch();
  const brushSize = useSelector(state => state.brushSize);
  const brushColor = useSelector(state => state.brushColor);
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    if (!canvasRef.current) return;

    const painter = new Canvas({
      canvas: canvasRef.current,
      brush: {
        size: brushSize,
        color: brushColor
      }
    });

    // Subscribe to store changes
    const unsubscribe = store.subscribe(() => {
      const newBrushSize = useSelector(state => state.brushSize);
      const newBrushColor = useSelector(state => state.brushColor);

      if (painter) {
        painter.brush.config.size = newBrushSize;
        painter.brush.config.color = newBrushColor;
      }
    });

    return () => {
      painter.destroy();
      unsubscribe();
    };
  }, [brushSize, brushColor, canvasRef]);

  return <canvas ref={canvasRef} width={800} height={600} />;
}

Testing React Components with Fuderu

Unit Testing with Jest and React Testing Library

import { render, screen, fireEvent } from "@testing-library/react";
import { Canvas } from "fuderu";
import DrawingCanvas from "./DrawingCanvas";

jest.mock("fuderu", () => ({
  Canvas: jest.fn().mockImplementation(() => ({
    destroy: jest.fn(),
    brush: {
      config: { size: 20, color: "#000000" },
    },
    putPoint: jest.fn(),
    render: jest.fn(),
    clear: jest.fn(),
    undo: jest.fn(),
    redo: jest.fn(),
  })),
}));

describe("DrawingCanvas", () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  test("renders canvas element", () => {
    render(<DrawingCanvas />);
    const canvasElement = screen.getByRole("img"); // or by testid
    expect(canvasElement).toBeInTheDocument();
  });

  test("calls putPoint on mouse down", () => {
    render(<DrawingCanvas />);
    const canvasElement = screen.getByRole("img");

    fireEvent.mouseDown(canvasElement, {
      clientX: 100,
      clientY: 100,
    });

    // @ts-ignore - accessing mocked implementation
    expect(Canvas.mock.instances[0].brush.putPoint).toHaveBeenCalledWith(
      100,
      100,
      0.5, // x, y, pressure (default)
    );
  });

  test("clears canvas when clear button clicked", () => {
    render(<DrawingCanvas />);
    const clearButton = screen.getByRole("button", { name: /clear/i });

    fireEvent.click(clearButton);

    // @ts-ignore - accessing mocked implementation
    expect(Canvas.mock.instances[0].brush.clear).toHaveBeenCalled();
  });
});

End-to-End Testing with Cypress

describe("Drawing Canvas", () => {
  beforeEach(() => {
    cy.visit("/drawing");
  });

  it("allows drawing with mouse", () => {
    cy.get("canvas")
      .trigger("mousedown", 100, 100)
      .trigger("mousemove", 150, 150)
      .trigger("mouseup", 200, 200);

    // Verify canvas was modified (implementation dependent)
    cy.canvas().should("have.been.modified");
  });

  it("responds to toolbar changes", () => {
    cy.get('input[type="color"]').first().select("#ff0000");
    cy.get("canvas")
      .trigger("mousedown", 100, 100)
      .trigger("mouseup", 150, 150);

    // Would need implementation-specific way to verify color
  });
});

Best Practices Summary

Do:

1. Use useEffect for canvas initialization - Properly handle component lifecycle
2. Always destroy canvas instances - Prevent memory leaks
3. Memoize expensive configurations - Prevent unnecessary recalculations
4. Debounce rapid updates - Improve performance for slider/color picker changes
5. Handle SSR properly - Use dynamic imports or conditional rendering
6. Leverage React's declarative nature - Let React manage the DOM when possible
7. Test edge cases - Rapid updates, component unmounting, resize events

Don't:

1. Initialize canvas in render function - Causes performance issues and potential memory leaks
2. Forget to cleanup effects - Leads to memory leaks and zombie canvases
3. Update canvas properties on every render - Causes unnecessary work
4. Ignore React Strict Mode warnings - Can indicate double-execution issues
5. Block the main thread with heavy computations - Use web workers or requestIdleCallback
6. Assume canvas size equals CSS size - Account for devicePixelRatio
7. Neglect touch events - Remember to handle touch alongside mouse events

Troubleshooting Common Issues

Canvas Not Drawing

• Check if canvas element exists and has dimensions
• Verify browser supports required APIs (PointerEvent, requestAnimationFrame)
• Confirm Canvas instance is properly destroyed and recreated
• Check for JavaScript errors in console

Poor Performance

• Measure actual FPS with performance monitoring
• Check for unnecessary re-renders in React DevTools
• Verify you're not creating new Canvas instances on every render
• Look for expensive operations in event handlers
• Consider reducing canvas size or disabling expensive features

Memory Leaks

• Ensure destroy() is called on all Canvas instances
• Check for lingering references in closures or timers
• Verify event listeners are properly removed
• Monitor memory usage in Chrome DevTools

SSR Issues

• Use typeof window !== "undefined" checks
• Employ dynamic imports with ssr: false
• Create appropriate placeholders for server-rendered content
• Handle hydration mismatches carefully

Resources

• React Documentation: useEffect Hook
• React Documentation: Rules of Hooks
• React Concurrent Mode
• Next.js Dynamic Import
• Redux Toolkit
• React Testing Library
• Cypress Testing

With these patterns and practices, you can create robust, performant Fuderu integrations in React applications that follow React best practices while leveraging the full power of the Fuderu drawing engine.