PIO Home library Examples panel doesn't group multi-file examples (works fine for platform examples)

fmazz97 · September 23, 2026, 12:35pm

Hi everyone,

While realizing a dual-framework library (Arduino + native ESP-IDF, same source shared between both), I ran into an inconsistency in the PIO Home → Libraries → Examples panel: examples declared with the structured name/base/files format in library.json don’t get grouped or labeled — each file becomes its own entry instead, using the bare filename as the label. So an ESP-IDF-style example (main/main.cpp, main/CMakeLists.txt, CMakeLists.txt, platformio.ini) shows up as four unrelated, oddly-named entries instead of one.

What’s interesting: platform examples (e.g. espressif32’s own examples) don’t have this problem — each platformio.ini correctly anchors one grouped project entry. I dug into the platformio-home source and traced the difference to two separate React containers with different grouping logic (detail-examples-block.jsx for libraries vs. platform-examples.jsx for platforms) — the library one never implements the “group everything under one project” step the platform one does.

Filed a detailed issue with the root cause and a suggested fix here:

github.com/platformio/platformio-home

[platformio-home] Library examples panel ignores examples[].name and flattens multi-file examples (file-level entries instead of project-level)

opened 12:34PM - 23 Sep 26 UTC

FMazz97

## Summary For libraries declaring the structured `examples` field in `library.…json` (objects with `name`/`base`/`files`, per the [official schema] https://docs.platformio.org/en/latest/manifests/library-json/fields/examples.html)), the PIO Home → Libraries → Examples panel does not group files by example and ignores the declared `name`. Each file in `files` becomes its own list entry, named after the bare filename (extension stripped) — multi-file examples with generic filenames (e.g. `main.cpp`, `CMakeLists.txt` — common in ESP-IDF-style projects) end up as multiple indistinguishable, duplicate- named entries. While investigating why my library examples were rendering incorrectly, I compared the behavior with the **Platform** examples are handled, where each `platformio.ini` correctly identifies one project = one entry, with all its files grouped underneath (`platform-examples.jsx`, `getItems()`). ## Root cause (traced in source) - **`library/containers/detail-examples-block.jsx`, `getGlobPatterns()`:** for structured examples, flattens `{base, files}` into a plain array of `base/filename` paths — the `name` field and the file-to-example association are both discarded at this step. - **Same file, `getRemoteItems()`:** builds one `ProjectExampleItem` **per file** in that flattened list, deriving `name` from the bare filename — never reads `example.name`. - **Comparison with Platform examples:** `platform/containers/platform-examples.jsx`, `getItems()`: finds each `platformio.ini`, creates **one** `ProjectExampleItem` per containing directory, then groups every file under that same directory as sources of that one item. This is the correct behavior and doesn't exist in the library-examples code path. ## Reproduction Given: ```json "examples": [ { "name": "My Example - ESP-IDF", "base": "examples/my_example", "files": ["main/main.cpp", "main/CMakeLists.txt", "CMakeLists.txt", "platformio.ini"] } ] ``` Expected: one entry, labeled "My Example - ESP-IDF", with 4 files grouped under it (consistent with the platform-examples behavior). Actual: 4 separate entries — "main", "CMakeLists", "CMakeLists", "platformio" — `name` never shown. Real-world example library hitting this: https://github.com/FMazz97/CS123x ## Suggested fix Port the grouping logic from `platform-examples.jsx`'s `getItems()` to `detail-examples-block.jsx`: when `examples[].name`/`base`/`files` is present, build one `ProjectExampleItem` per declared example (using `example.name` as the label) with all its `files` as sources, instead of flattening to file-level entries. ## Bonus: "Import" button for examples containing `platformio.ini` Platform examples show an "Import Project" action when a `platformio.ini` is present in the example. Library examples currently don't — even when the example itself ships a ready-to-use `platformio.ini` (a common pattern for libraries supporting multiple frameworks, e.g. Arduino + ESP-IDF, here each example is a self-contained buildable project). Extending the same "Import" affordance to library examples whenever `platformio.ini` is detected in the example's files would make this workflow consistent between platforms and libraries. Happy to help test a fix against a real dual-framework library if useful.

Also suggesting, while at it, extending the “Import Project” button (already available for platform examples with a platformio.ini) to library examples that ship one too — useful for libraries where an example is a self-contained, ready-to-build project rather than a single source file.

Curious if others have run into the same thing, or if there’s context on why the two code paths diverged. Happy to help test a fix if it moves forward.

loveforcircuits · October 8, 2026, 12:03pm

Good investigation. The distinction between the library and platform example handling explains the behavior quite well.

The examples[].name field should reasonably be expected to define the project-level entry, especially when base and files describe a multi-file example. Flattening those files into separate entries makes structured library examples considerably less useful.

Supporting platformio.ini as an importable project would also make sense. It would bring library examples closer to the behavior users already get with platform examples.

Hopefully the maintainers can reuse the grouping logic from platform-examples.jsx rather than maintaining two different behaviors.