BUG-037
ID:BUG-037Status:confirmed

The runes.prefer docs example uses an npm name that mergePlugins never matches

Found by WORK-634 (#695).

site/content/extend/plugin-authoring/authoring.md ("Name Collision Resolution") shows:

Severity:minorSource:SPEC-153
claude/post-v0.38-roadmap-jb7pie View source
Branches 2
claude/post-v0.38-roadmap-jb7pie current confirmed
claude/v041-plan-runes-keep-content confirmedmain confirmed
History 1
  1. c14f915
    Created (confirmed)by bjornolofandersson

Steps to Reproduce

  1. Configure two plugins that both define hero, and copy the docs example: "runes": { "prefer": { "hero": "@my-org/custom" } }.
  2. Build a page using {% hero %}.

Expected

The documented example works when copied.

Actual

The preference is ignored with no warning. The collision resolves by the default rule.

Fix

Either:

  • correct the examples to the short name, and state which name is meant; or
  • accept the npm name as well in mergePlugins.

The second is friendlier, since the npm name is the one a user sees in refrakt.config.json's plugins list. Either way, an unknown prefer value should warn rather than be ignored.