Skip to content

fix: treat JS null as std::nullopt in the Optional converter - #2049

Closed
jasonjtgao wants to merge 1 commit into
margelo:mainfrom
jasonjtgao:fix/optional-null-conversion
Closed

jasonjtgao wants to merge 1 commit into
margelo:mainfrom
jasonjtgao:fix/optional-null-conversion

Conversation

@jasonjtgao

Copy link
Copy Markdown

Summary

JSIConverter<std::optional<T>>::fromJSI maps only undefined to std::nullopt. React Native delivers a removed prop as JS null — that is React's documented "set property to default" contract (see ReactStylesDiffMap's comment: "value is null (this is a way React communicates change to default)"). So an optional prop that is cleared at runtime (rather than never set) falls through to the inner converter and throws — e.g. JSIConverter<std::string>::fromJSI calls arg.asString(runtime) on null and raises "value is null, expected a string".

This PR maps null to std::nullopt in fromJSI and accepts it in canConvert, exactly like undefined. toJSI is unchanged (std::nullopt still converts to undefined, so no host observes a changed output direction).

Reproduction

A Nitro view with an optional, theme-driven prop (e.g. deskColor?: string on a canvas view):

  1. Set the prop to a string while the system is in dark mode → works.
  2. Switch the system back to light mode, which removes the prop → React commits the update with null → the generated prop parser throws → "Exception in HostFunction: .: value is null, expected a string".

An optional prop that is simply never set does not hit this (the key is absent from raw props) — only the set-then-cleared transition does, which is why it stayed latent.

Validation

We have been carrying the identical two-guard change as a local patch against react-native-nitro-modules@0.35.9 in production integration (unit tests + on-device verification of the set → clear → set cycle). Happy to add a test case here if you point me at the preferred harness for converter-level tests.

🤖 Generated with Claude Code

React Native delivers a removed prop as JS `null` (not `undefined`) —
that is React's documented "set property to default" contract
(ReactStylesDiffMap). The Optional converter only mapped `undefined` to
`std::nullopt`, so an optional prop cleared at runtime fell through to
the inner converter and threw (e.g. `asString()` on `null` →
"value is null, expected a string").

Map `null` to `std::nullopt` in `fromJSI` and accept it in
`canConvert`, exactly like `undefined`. `toJSI` is unchanged
(`std::nullopt` still converts to `undefined`).

Found in device UAT of a Nitro view whose optional `deskColor` prop is
theme-driven: flipping the app back to light mode (which removes the prop)
crashed the host function. We have been carrying the identical change as a
local patch on react-native-nitro-modules 0.35.9 (unit tests + device
verification) and would like to drop it once this ships.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 5, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
nitro-docs Skipped Skipped Nov 5, 2026 6:05am UTC

Request Review

@mrousavy mrousavy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall you are right that this breaks in React Native, although this is quite a critical behavioural change and we probably would need some more tests to verify this.

And I am not sure if something breaks - I mean technically a variant consisting of an optional property or null could now break. I am not sure if @chrispader uses this pattern in Nitro SQLite but if yes we probably shouldn't really do this - instead we should probably try to get a change into React/React Native to provide default values a different way, e.g. pass undefined instead of null. Or override it in the component view config.

Comment on lines 22 to +26
// std::optional<T> <> T | undefined
// `null` is also accepted as "absent": React Native delivers a REMOVED prop
// as JS `null` (not `undefined`), so an optional prop that is cleared at
// runtime arrives here as `null` and must convert to `std::nullopt` rather
// than fall through to the inner converter (where it would throw).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// std::optional<T> <> T | undefined
// `null` is also accepted as "absent": React Native delivers a REMOVED prop
// as JS `null` (not `undefined`), so an optional prop that is cleared at
// runtime arrives here as `null` and must convert to `std::nullopt` rather
// than fall through to the inner converter (where it would throw).
// std::optional<T> <> T | undefined | null

@mrousavy

mrousavy commented Nov 9, 2026

Copy link
Copy Markdown
Member

This is a breaking change and not a fix - it's a patch specifically for one use-case, that breaks the behaviour for many others.
React Native should have an option to configure the value for resetting props, I created an issue in the RN repo: react/react-native#59884

We should have something like defaultValue or resetValue in our RN View Config. This is the clean solution.

TypeScript also doesn't allow null for optional values, so not only would this be a breaking change, it'd also go against the TypeScript types/standard.

@mrousavy mrousavy closed this Nov 9, 2026

This branch was previously deployed

1 inactive deployment
Preview — c60222a0 Deployed Nov 5, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants