Polotno Design Editor Framework

Common errors

• Could not resolve dependency: npm error peer react@"^18.2.0" from polotno@2.x.x

  cause Attempting to install Polotno in a project using React 19, which has a conflicting peer dependency range.
  fix Add resolutions/overrides to your `package.json` to force `react`, `react-dom`, and `react-konva` (if used) to version 18.2.0, e.g., `"overrides": { "polotno": { "react": "18.2.0", "react-dom": "18.2.0", "react-konva": "^18.2.0" } }`.

• Uncaught TypeError: Cannot read properties of undefined (reading 'ReactCurrentOwner')

  cause This error typically occurs when different versions of React are loaded, or React context is lost, often associated with React 19 compatibility issues.
  fix Ensure all React-related packages (React, ReactDOM, Polotno, and any other UI libraries) resolve to the exact same React 18 version. Use package manager overrides as described for the `peer react` dependency error.

• Error: Minified React error #185; Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate.

  cause An infinite rendering loop, often when Polotno's MobX store reactivity conflicts with another framework's reactivity system (e.g., Vue 3) or when a React component's `setState` is called synchronously within its render or update phase without proper guarding.
  fix When embedding Polotno in a non-React app, ensure the React part is isolated. For Vue 3, wrap the React editor mount point with `mobx-vue-lite`'s `Observer` component. Review component lifecycle for unintended state updates.

• Memory leak / "Page unresponsive" when combining all text effects with an animation on a Text element.

  cause Intensive rendering or state updates, particularly with complex text rendering, filters, and animations, can overwhelm browser resources.
  fix Simplify design elements, reduce the number of simultaneous effects, or optimize animations for performance. Consider reporting the specific use case to Polotno support for potential library-level optimizations.

Warnings

• breaking Polotno currently relies on React 18.2.0. Using React 19 may cause dependency resolution issues or runtime errors like `Cannot read properties of undefined (reading 'ReactCurrentOwner')`.
  Fix: You must explicitly override `react`, `react-dom`, and `react-konva` dependencies to force them to React 18 in your `package.json` to ensure compatibility. Refer to the official Polotno documentation for specific override configurations.
• gotcha A Polotno API key is required for production usage. While a free key is available for development, commercial use necessitates obtaining a license.
  Fix: Register for an API key at Polotno's website. The `createStore` function requires the `key` option. Setting `showCredit: true` can display a back-link, which can be disabled with a paid license.
• gotcha Integrating Polotno (a React-based library using MobX) into other JavaScript frameworks like Vue or Angular directly can lead to 'Maximum update depth exceeded' errors due to reactivity conflicts.
  Fix: It is recommended to encapsulate the Polotno editor within its own isolated React component and then mount that React component into your host framework. For MobX reactivity with Vue, ensure proper `mobx-vue-lite` or `mobx-angular` integration and `Observer` wrapping.
• gotcha Complex text elements combined with multiple filter-based effects and animations can lead to significant memory usage, potentially causing browser tabs to become unresponsive or crash.
  Fix: Monitor memory usage with complex designs. Simplify text effects or animations where possible. Report specific reproducible cases to Polotno support.
• gotcha When using `polotno-node` for server-side rendering, especially in environments like AWS Lambda, complex designs may require a substantial increase in allocated memory to prevent 'Out of Memory' errors or timeouts.
  Fix: Increase the memory limit for your serverless function (e.g., AWS Lambda memory from default to maximum for complex designs). Optimize JSON payloads for simpler designs if possible.

Install

• npm install polotno npm
• yarn add polotno yarn
• pnpm add polotno pnpm

Imports

• PolotnoContainer
  wrong:

  const PolotnoContainer = require('polotno').PolotnoContainer;

  correct:

  import { PolotnoContainer } from 'polotno';

  Polotno is primarily designed for ES Module environments. CommonJS `require` is not officially supported for UI components and may lead to issues.
• createStore
  wrong:

  import createStore from 'polotno/model/store';

  correct:

  import { createStore } from 'polotno/model/store';

  `createStore` is a named export from its specific module path. Direct default import is incorrect.
• Toolbar
  wrong:

  import { Toolbar } from 'polotno';

  correct:

  import { Toolbar } from 'polotno/toolbar/toolbar';

  Many UI components are imported from specific sub-paths for better tree-shaking and modularity.

Quickstart

This quickstart initializes a basic Polotno design editor with a side panel, toolbar, and workspace, rendered as a React component. It sets up the core store, adds a default page, and includes necessary CSS. An API key is required.

import React from 'react';
import ReactDOM from 'react-dom/client';
import { PolotnoContainer, SidePanelWrap, WorkspaceWrap } from 'polotno';
import { Toolbar } from 'polotno/toolbar/toolbar';
import { ZoomButtons } from 'polotno/toolbar/zoom-buttons';
import { SidePanel } from 'polotno/side-panel';
import { Workspace } from 'polotno/canvas/workspace';
import { createStore } from 'polotno/model/store';
import '@blueprintjs/core/lib/css/blueprint.css'; // Polotno uses Blueprint.js styles

const store = createStore({
  key: process.env.POLOTNO_API_KEY ?? 'YOUR_FREE_API_KEY_HERE',
  showCredit: true // Set to false with a paid license to hide the back-link
});

// Add a default page to the store
store.addPage();

export const PolotnoEditor = () => {
  return (
    <PolotnoContainer style={{ width: '100vw', height: '100vh' }}>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} downloadButtonEnabled />
        <Workspace store={store} />
        <ZoomButtons store={store} />
      </WorkspaceWrap>
    </PolotnoContainer>
  );
};

// Example of how to render it in a root (e.g., in index.tsx)
/*
const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(
  <React.StrictMode>
    <PolotnoEditor />
  </React.StrictMode>
);
*/