Skip to content

Add preferredPrefix Support #129

@iObject

Description

@iObject

Allow ROPM modules to declare a preferredPrefix in their package.json ropm config block. When ROPM installs such a module, it should use the declared prefix instead of deriving one from the package name or scope — unless the user has explicitly provided an alias at install time.

Currently, ROPM derives a module's prefix from its package name or npm scope (e.g. @rokucommunity/promisesrokucommunity_promises). This works fine for most cases, but module authors often know a cleaner, shorter, or more idiomatic prefix that downstream consumers should use. Without a way to declare this preference, every consumer ends up with verbose, auto-derived prefixes — and namespace rewrites inside .brs files reflect those verbose names.


Desired Behavior

When a module author wants to suggest a prefix, they add a preferredPrefix field to the ropm config in their package.json:

{
  "name": "@rokucommunity/promises",
  "ropm": {
    "preferredPrefix": "promises"
  }
}

During ropm copy, ROPM should:

  1. Detect the preferredPrefix field in the installed module's package.json.
  2. Use that value as the module's prefix instead of the auto-derived one.
  3. Apply the prefix consistently: folder naming under roku_modules/, and all namespace rewrites inside copied .brs and .xml files.
  4. Log clearly that the preferred prefix was found and is being used.

Alias Override Rule

If the user provided an explicit alias at install time, the preferredPrefix must be ignored entirely. The user-supplied alias always takes precedence.

Example — alias wins:

npm install mypkg@npm:@rokucommunity/promises
# ropm should use "mypkg", not "promises"

Example — preferredPrefix wins (no alias):

npm install @rokucommunity/promises
# ropm should use "promises" (from preferredPrefix), not "rokucommunity_promises"

The alias detection logic should compare the local package name against the resolved package name to determine whether an alias was explicitly provided.


Logging

ROPM should emit informative output during copy so users understand why a non-default prefix is being used:

  • When preferredPrefix is found and used: indicate that the default prefix was overridden by the module's declared preference.
  • When an alias is present: use the alias silently (current behavior — no change needed).

Acceptance Criteria

  • preferredPrefix in a module's package.json ropm config is respected during ropm copy.
  • Files are copied into roku_modules/<preferredPrefix>/ when preferredPrefix is active.
  • Namespace strings inside copied .brs files are rewritten to use the resolved prefix.
  • A user-supplied install alias overrides preferredPrefix.
  • If preferredPrefix is absent, existing default/scoped prefix behavior is unchanged.
  • Unit tests cover: preferred prefix used, alias overrides preferred prefix, no preferred prefix (regression).
  • Output logging makes the prefix resolution decision visible to the user.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions