@P5-wrapper/next

A Next.js specific wrapper for @p5-wrapper/react, a component to integrate P5.js sketches into React apps.

Note:

This library simply re-exports the @p5-wrapper/react component as a Next.js dynamic component using next/dynamic with server-side rendering disabled. Nothing more.

For more in-depth information on the base component, check the documentation via the @p5-wrapper/react docs.

Installation

@p5-wrapper/react, p5, next, react and react-dom are peer dependencies and must be installed in your project:

[npm|yarn|pnpm] [install|add] @p5-wrapper/next @p5-wrapper/react p5 next react react-dom

Usage

To use the component in your Next.js project, simply import it like so:

import { NextReactP5Wrapper } from "@p5-wrapper/next";
import { type Sketch } from "@p5-wrapper/react";
import React from "react";

const sketch: Sketch = (p5) => {
  p5.setup = () => p5.createCanvas(600, 400, p5.WEBGL);

  p5.draw = () => {
    p5.background(250);
    p5.normalMaterial();
    p5.push();
    p5.rotateZ(p5.frameCount * 0.01);
    p5.rotateX(p5.frameCount * 0.01);
    p5.rotateY(p5.frameCount * 0.01);
    p5.plane(100);
    p5.pop();
  };
};

export default function Page() {
  return <NextReactP5Wrapper sketch={sketch} />;
}

All props supported by P5Canvas can be passed straight through — NextReactP5Wrapper forwards everything to the underlying component. See the @p5-wrapper/react documentation for the full list of props, custom updaters, fallback UIs, and error and loading handling.

Why dynamic with ssr: false?

p5 sketches manipulate the DOM and browser APIs directly, which do not exist during server-side rendering. The wrapper therefore loads P5Canvas client side only, which is also what Next.js recommends for browser-only libraries.

Development

The source code for the component is in the src directory. You will need Node.js and pnpm — the exact versions are pinned in package.json.

To run the Vite dev tooling:

pnpm dev

Contributing

Before opening a pull request, make sure your changes pass every quality gate:

pnpm integrate

This runs the same checks as CI — formatting, linting, tests, and builds. Pull requests are reviewed against the pull request template and must keep the public API in src/main.tsx backwards compatible. Commits follow the conventional commit style (feat:, fix:, chore:, etc.) — emoji prefixes are only used by automated pull requests.

The typescript dependency is pinned to the latest 6.x.x release on purpose: TypeScript 7 (Go-based) is not yet feature compatible with the JavaScript-based v6 API that the build toolchain builds on. Please do not bump past 6.x.x or widen the pin in pull requests — we wait for full feature parity before migrating to v7, no half measures.

AI-assisted contributions

Contributions developed with the assistance of an AI agent are welcome, but you — the developer — are always the ultimately responsible individual for your contributions. AI agents cannot author or certify them. When AI assistance is used:

• Commit with --signoff (git commit -s) so that you certify the Developer Certificate of Origin for the work yourself
• Optionally credit the agent with an Assisted-by: LLM trailer in the commit message, as recommended by the Linux kernel team
• Ensure all work adheres to the MIT licence

See AGENTS.md for the full set of rules agents follow in this repository.