refactor: alter Android API for loading the JS bundle from disk

[artus9033]

Summary

This PR:

• documents changes that were added in feat(android): allow bundle file path #200
• alters the API to have a second, explicit option that controls loading of the JS bundle from disk
• adds the right changeset for a future release

Test plan

CI green.

[artus9033]

Hi @gronxb , FYI: after second thoughts, I think it will be better to expose the functionality with a second argument, bundleFilePath, that allows to load the JS bundle from disk. This will be more verbose for the existing users who wouldn't need to load from disk, and will be safer in the sense that currently there's no expectation that the bundleAssetPath can have this behaviour. This way, we'll match the style in which RN implements this functionality. I also updated the docs + added a changeset.

[gronxb]

I understand the intention behind this decision, which is to respect the existing parameters provided by React Native. However, I’d like to add one point: I think the interface exposed to users should remain consistent with the way things are configured in MainApplication.kt.

Values such as bundleAssetPath and bundleFilePath are essentially interfaces that resemble internal APIs closely tied to React Native’s internal implementation.

In a real greenfield environment, MainApplication.kt only passes a single value—jsBundleFilePath—and all subsequent handling (whether it comes from assets or the file system) is processed entirely inside the internal logic.
In other words, from the user’s perspective, there is no need to know the actual location or form of the bundle. They only need to specify the “entry point of the JS bundle.”

From this perspective, I think it would be more natural for ReactNativeBrownfield to unify the externally exposed interface under jsBundleFilePath as well.
Existing values like bundleAssetPath should remain only as internal implementation details if necessary, and ideally should be hidden from the public API.

What do you think ?

[artus9033]

I agree with your reasoning, it's correct, but on the other hand, since loading from an arbitrary disk path may be security-concerning, then having a separate, verbose argument for that feature is a good option. I think this might be the reason why RN logic itself does not unify those 2 arguments into one, but just gives the path argument priority over the asset locator.

For this reason, just to have an additive change that 1) does not surprise existing users and 2) explicitly states the value passed in can load an arbitrary JS bundle from disk, is better. This will allow us to release a patch version and have an easy adoption for ones that want to use this feature. There will be no 'surprises' that the existing arg does something unexpected.

Also, while unifying to just one ar may make sense, on the other hand the arg is currently named bundleAssetPath, which would be non-descriptive of the new functionality - loading from a non-asset file. Separating this gives space for a new, descriptive param.

[gronxb]

I understand, since breaking changes were also my biggest concern! Thank you.

[okwasniewski]

[artus9033]

Awesome, I'm glad we reached the agreement! We'll try to ship this soon and let you know to test it from the published NPM package 🔧

[artus9033]

Hi @gronxb - the newest version of @callstack/react-native-brownfield that includes the changes is 2.1.0, you can test it from NPM.