fix(app): keep local/git package specifiers whole when resolving inst…

[masenf]

closes #7117

All Submissions:

• Have you followed the guidelines stated in CONTRIBUTING.md file?
• Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

• Bug fix (non-breaking change which fixes an issue)
• This change requires a documentation update

Changes To Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully ran tests with your changes locally?

---

The bug

App._get_frontend_package_name split everything after package@ at the first slash, treating the leading segment as a version and the remainder as a package subpath. That is correct for @scope/pkg@1.0.0/dist/style.css, but wrong for specifiers that name a location rather than a version. A :-in-version check rescued protocol forms (file:, github:), leaving bare paths to be truncated:

import name	resolved install spec (before)
@masenf/hello-react@../hello-react	@masenf/hello-react@..
@masenf/hello-react@../hello-react.tgz	@masenf/hello-react@..
@masenf/hello-react@/opt/hello-react	@masenf/hello-react@

bun then failed with exactly what the issue reports:

error: Could not find package.json for "file:.." dependency "@masenf/hello-react"
error: @masenf/hello-react@.. failed to resolve

The change

A new _is_location_specifier helper: the leading segment is split off as a version only when the specifier is not a location — i.e. not a protocol form (:), not a git ref (#), and not a relative/absolute/home-relative path. Locations now reach the package manager unmodified.

The package_name == library_name branch this replaces produced a string identical to the generic one, so it is folded in. Version+subpath imports (react-map-gl@1.0.0/maplibre), protocol forms, URLs and plain subpath imports all resolve exactly as before.

Verification

Three regression tests added to tests/units/test_app.py (all fail before the fix). Beyond unit tests, this was verified end-to-end with an app wrapping @masenf/hello-react via reflex export --frontend-only:

• @masenf/hello-react@../masenf-hello-react-0.1.0.tgz — installs, production build succeeds, Counter in the bundle.
• @masenf/hello-react@../hello-react — .web/package.json records "@masenf/hello-react": "../hello-react", lockfile resolves file:../hello-react, build succeeds.

uv run ruff check . / ruff format . clean, uv run pyright reflex tests reports 0 errors, and the unit suite passes (6904 passed; the two failures in tests/units/utils/test_processes.py::test_is_process_on_port_* are pre-existing and environment-dependent — they inspect real listening ports — and are untouched by this change).

Docs

For a local directory dependency, bun links the package's files in place, so the bundler resolves that package's own runtime dependencies from the source directory rather than from .web/node_modules (the first e2e run failed on Rolldown failed to resolve import "lodash" until hello-react/node_modules existed). That is package-manager/bundler behavior rather than a Reflex bug, so docs/wrapping-react/local-packages.md now notes it: run npm install inside the local package directory, or reference a packed archive.

Known limitation (unchanged)

The bare GitHub shorthand @scope/pkg@user/repo is genuinely ambiguous with @scope/pkg@dist-tag/subpath and still resolves to @scope/pkg@user. The documented form github:user/repo works; disambiguating the shorthand would require guessing, so it is left alone.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LwE92843n9iYDVR7yfjwJX

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge and preserves the existing package-resolution behavior while fixing local and git location specifiers.

Summary

This PR fixes frontend dependency resolution so local-path, protocol-based, and git package specifiers containing slashes reach the package manager intact.

• Adds location-specifier classification while preserving existing version-plus-subpath normalization.
• Adds regression coverage for relative, absolute, home-relative, file, GitHub, and git-ref specifiers, including scoped package subpaths and deduplication.
• Documents dependency installation behavior for linked local package directories.
• Adds the required user-facing bug-fix news fragment.

_{Reviews (1) · Last reviewed commit: "fix(app): keep local/git package specifi..."}

[codspeed-hq]

Merging this PR will not alter performance

✅ 40 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing masenf:claude/friendly-johnson-mes98o (f1824f3) with main (2f63cb3)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[cubic-dev-ai]

No issues found across 4 files

_{Re-trigger cubic}