The latest release of hermes-memory-installer carries a targeted fix: memory sidecar modules are now properly loaded from runtime scripts. This change corrects an inconsistency where sidecar modules—small wrappers that attach to Hermes memory management hooks—were initialized during build time but not activated in the runtime script context. For developers who depend on accurate memory profiling in production or debug builds, this fix closes a subtle but critical gap.
Hermes-memory-installer is a tool that configures the Hermes JavaScript engine to surface fine-grained memory allocation events, GC cycles, and heap snapshots through pluggable sidecar modules. These modules are designed to be environment-aware, attaching to the engine when the runtime script executes. Prior to this fix, the installer would reference sidecar paths in the build configuration but fail to ensure they were required from the runtime entry point. The result: sidecar modules were often skipped entirely, leading to false negatives in memory monitoring or crashes when profiling APIs were called but no sidecar was registered.
The fix itself is straightforward but impactful. The installer now injects a require call for each sidecar module into the generated runtime script, not just the build assets. This guarantees that the module is loaded and initialized synchronously when the engine starts, before any application code runs. The change touches the core code generation logic inside hermes-memory-installer that produces the final runtime configuration bundle.
Consider the typical usage pattern. Before the fix, a developer might define a custom sidecar that tracks native allocation sizes:
// Runtime entry script (before fix)
const { createMemorySidecar } = require('hermes-memory-installer');
// Sidecar is created but not automatically attached to runtime
// module.exports.boot = ... // sidecar often missing
After the update, the installer handles this automatically:
// Generated runtime bootstrap (after fix)
const sidecarLoader = require('hermes-memory-installer/sidecar-loader');
const sidecar = sidecarLoader('sidecar-custom-allocation');
// sidecar is now attached to the Hermes engine instance
module.exports.boot = function (engine) {
engine.setMemorySidecar(sidecar);
};
This small shift—loading from runtime scripts rather than relying on build-time placement—changes the activation point from "available at link time" to "registered at engine start." It mirrors the lifecycle that sidecar modules expect: they must be bound to a live engine context, not just to a compiled binary.
For experienced developers, this matters most in hybrid environments where Hermes is used alongside native modules or when running non-standard build toolchains. The old behavior could mask memory reporting bugs that only appear when profiling code runs before the sidecar is fully registered. With this fix, the sidecar lifecycle is deterministic. The installer respects the contract that runtime scripts are the sole source of truth for engine initialization.
Operationally, upgrading means regenerating the runtime script if you use a custom launcher. The installer will now output a runtime.hermes.js or equivalent file that includes the sidecar require statements. If you manage runtime scripts manually, you must re-run the installer to pick up the fix. No sidecar configuration changes are needed—the update is backward compatible for existing sidecar definitions.
One nuance: while the fix ensures sidecar modules are loaded, it does not change how they are selected. Developers still specify sidecars through the installer's configuration object. The improvement is purely in the load sequence. If you were already using the installer's defaults, the update is transparent. If you had patched around the missing loads, you can now remove those workarounds.
The underlying reason the bug existed is that hermes-memory-installer originally separated build and runtime concerns too strictly. Sidecar modules needed to be compiled with engine-specific symbols, so they were handled during the build phase. But the engine only activates sidecars when a runtime script calls the registration function. The two steps were never properly linked. This fix bridges that gap without adding new APIs.
From a performance perspective, loading from runtime scripts adds negligible startup overhead—sidecar modules are small and initialization is eager but cheap. The larger benefit is correctness: memory tracking now works reliably on first access, regardless of how the application's own initialization code is ordered.
For teams debugging React Native apps with heavy JS execution, this fix eliminates a common source of confusion where memory tools reported "sidecar not found" errors only in specific builds. With the sidecar guaranteed to be loaded from the runtime script, those errors should become rare.
In summary, this update makes hermes-memory-installer more predictable by enforcing a simple rule: sidecar modules must be registered by the runtime script, not assumed from the build. If you use this installer, regenerate your runtime configuration and verify that sidecar require lines appear in your bootstrapping code. The fix is small in the changelog but large for anyone relying on precise memory introspection in Hermes.
Top comments (0)