Respect root bun.lock during frontend installs

[GautamBytes]

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)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 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?

Description

This PR fixes Bun lockfile persistence for Reflex apps by treating the project root bun.lock as the canonical lockfile and mirroring it into .web before frontend package manager commands run.

Without this change, .web/ reinitialization and frontend package installs could overwrite or ignore the effective Bun lockfile state, which meant users could not reliably commit and reuse Bun’s resolved dependency graph. That made it difficult to pin direct and transitive frontend dependencies.

This change:

• adds helpers to mirror bun.lock between the app root and .web
• restores .web/bun.lock from the root lock during .web initialization
• persists the final .web/bun.lock back to the root after successful Bun package operations
• updates frontend package install caching so lockfile changes and current extra package state are respected
• removes stale custom frontend packages from .web/package.json when they are no longer desired
• documents that bun.lock should live at the project root and be committed to version control

closes #6268

[greptile-apps]

Greptile Summary

This PR adds bun lockfile persistence for Reflex apps by treating the project-root bun.lock as the canonical source of truth and mirroring it into .web around frontend package operations. The implementation is logically sound and the test suite is thorough — covering npm, partial install failure, cache invalidation on lockfile changes, stale package removal, and cache-hit .web lock refresh.

• Adds LOCKFILE_PATH = "bun.lock" constant to the Bun class in installer.py
• Introduces sync_root_bun_lock_to_web() / sync_web_bun_lock_to_root() helpers in frontend_skeleton.py
• Modifies install_frontend_packages() to sync lockfiles, include the bun lock SHA-256 in the cache key, and remove stale custom packages before reinstalling
• Documents that bun.lock should live at the project root and be committed to version control
• All remaining findings are P2 style/documentation concerns: private _read_cached_procedure_file/_write_cached_procedure_file imports, undocumented CWD assumption in get_root_bun_lock_path(), and a missing intent comment on the unconditional sync_root_bun_lock_to_web() call when npm is active

Confidence Score: 4/5

Safe to merge; all remaining findings are P2 style and documentation concerns that do not affect correctness.

Logic is sound and tests are comprehensive with no P0/P1 issues. Score is 4 rather than 5 because the private-API imports (_read_cached_procedure_file/_write_cached_procedure_file) create a coupling to reflex_base internals that could silently break on an internal refactor.

reflex/utils/js_runtimes.py (private imports) and reflex/utils/frontend_skeleton.py (undocumented CWD assumption in get_root_bun_lock_path)

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/constants/installer.py	Adds LOCKFILE_PATH = "bun.lock" constant to the Bun class, consistent with existing CONFIG_PATH pattern — clean and correct.
reflex/utils/frontend_skeleton.py	Adds well-structured bun lock sync helpers; minor concern that get_root_bun_lock_path() uses Path.cwd() without documenting the CWD dependency in its docstring.
reflex/utils/js_runtimes.py	Core lockfile sync and stale-package-removal logic is correct and well-tested, but imports private _read_cached_procedure_file/_write_cached_procedure_file from reflex_base.utils.decorator internals.
tests/units/test_prerequisites.py	Thorough new tests cover npm case, partial install failure, cache invalidation on lockfile changes, stale package removal, and cache-hit web lock refresh.
reflex/docs/getting_started/project-structure.md	Accurate and helpful addition documenting that bun.lock lives at the project root and should be committed to version control.

Sequence Diagram

sequenceDiagram
    participant C as Caller
    participant IR as install_frontend_packages
    participant FS as frontend_skeleton
    participant PM as PackageManager (bun/npm)
    participant Cache as CacheFile

    C->>IR: install_frontend_packages(packages, config)
    IR->>IR: compute cache_payload (incl. bun lock SHA-256)
    IR->>FS: sync_root_bun_lock_to_web()
    FS-->>IR: root bun.lock mirrored to .web/ (or .web/bun.lock removed if no root)
    IR->>Cache: _read_cached_procedure_file()
    Cache-->>IR: (cached_payload, _)
    alt cache hit (payload matches)
        IR-->>C: return early
    else cache miss
        IR->>PM: remove stale packages (if any)
        IR->>PM: bun install --legacy-peer-deps
        opt development deps exist
            IR->>PM: bun add -d dev-deps
        end
        opt custom packages exist
            IR->>PM: bun add custom-packages
        end
        IR->>FS: sync_web_bun_lock_to_root()
        FS-->>IR: .web/bun.lock persisted back to project root
        IR->>Cache: _write_cached_procedure_file(new_payload)
        IR-->>C: done
    end

Loading

_{Reviews (1): Last reviewed commit: "Persist and respect root bun.lock" | Re-trigger Greptile}