What’s working and what’s missing in Penpot plugins?

IvanTheGeek · March 28, 2026, 11:21am

I hit a real Plugin API limitation that might be worth documenting more clearly.

In live plugin/MCP work, top-level board creation and top-level reparenting followed the active page. So for automation, I had to:

switch to the target page first
then create or reorganize top-level boards
then verify where they actually landed

This came up while building reusable Event Modeling slice components across Components and PATHS pages. The closest GitHub issue I found is:

github.com/penpot/penpot

Plugin API: document createComponent() board-on-root requirement and cross-page reparenting limitation

opened 12:54PM - 19 Mar 26 UTC

abhishek-mittal

bug managed on taiga

## Summary Two undocumented constraints in the Penpot Plugin API cause silent f…ailures for agents and plugin authors who are not already aware of them. --- ## Issue 1 — `createComponent()` only works with freshly inserted root-level boards ### Observed behaviour `penpot.library.local.createComponent([shape])` silently produces an empty / broken component when `shape` is an existing page-owned board (e.g. one retrieved via `penpotUtils.findShapeById()`, cloned, or previously reparented). ### Required (but undocumented) precondition The shape(s) passed to `createComponent()` **must** be: 1. Created in the same execution context via `penpot.createBoard()` 2. Inserted into `penpot.root` **before** `createComponent()` is called ### Suggested documentation addition A note in the `Library.createComponent()` API docs explaining the required sequence: ```ts const board = penpot.createBoard(); penpot.root.insertChild(penpot.root.children.length, board); // required BEFORE createComponent const component = penpot.library.local.createComponent([board]); component.name = 'Buttons/Primary'; // '/' creates nested groups in the Assets panel ``` --- ## Issue 2 — Cross-page reparenting is not supported by the Plugin API ### Observed behaviour Component main instances created by `createComponent()` always land on the **current active page**. There is no Plugin API method to move a shape to a different page after creation. ### Impact When a component is created on one page and the main instance needs to live on a dedicated Design System page, the only option is to move it manually in the Penpot UI. This is not documented and leaves plugin authors without a programmatic alternative. ### Suggested documentation addition A note on `createComponent()` (or the `Shape` reparenting section) that: - Explicitly states cross-page reparenting is unsupported - Recommends the manual workaround (drag in Penpot UI) --- ## Additional context The `'/'` separator in `component.name` **does** create nested groups in the Assets panel automatically (this works as expected and is a useful, undocumented feature worth highlighting in positive docs too). Encountered while building a design-system automation plugin using the MCP Plugin API.

I added more concrete reproduction context there.

Topic		Replies	Views
Join as a Beta Tester for Penpot Plugins. Creators wanted! Help us improve Penpot	22	3988	September 5, 2024
Penpot 2.3 release: Plugin system is here! 🧩 Product updates	6	840	November 22, 2024
The Plugin System beta test is over. How did it go? Events and Announcements	1	567	October 4, 2024
I think I know why penpot isn't main stream yet! Feature requests	21	1099	April 16, 2025
Are you new to the Penpot community? That's how you can get started! Ask the community community	1	3223	January 17, 2023

What’s working and what’s missing in Penpot plugins?

Related topics

Design as Code