Add docs on `weak-node-api`

[kraenhansen]

We're not mentioning the requirement of linking against the weak-node-api library in https://github.com/callstackincubator/react-native-node-api/blob/main/docs/PREBUILDS.md.

[reckziegelwilliam]

Hi! I'd like to add docs on weak-node-api.

[kraenhansen]

@reckziegelwilliam that would be great 👍

I'd like for you to:

1. read through the existing README.md,
2. read the documentation on PREBUILDS.md,
3. formulate a few questions that need clarification, in your view, based on what you've read and post those below,
4. outline a high-level plan on what changes you think is needed to either or documents that we're missing entirely.

When done, I'll assign the issue to you, review and merge according to your plan.

[reckziegelwilliam]

Hi @kraenhansen, thanks for the guidance 🙌

I’ve read through:

• weak-node-api’s README.md
• docs/PREBUILDS.md in this repo

Below are a few clarifying questions and then a high-level plan for the docs changes.

---

Clarifying questions

1. Where should the main requirement live?
   Would you prefer the explicit “you must link against weak-node-api” requirement to live primarily in docs/PREBUILDS.md (with a short pointer from the weak-node-api README), or should both documents carry a small self-contained explanation?

2. Platform scope
   Should we describe linking against weak-node-api as:

   • primarily an Android requirement (since the README.md explains the Android dynamic linker issue), or
   • a requirement for all React Native prebuilds (*.android.node and *.apple.node) going forward?

3. Build tooling vs. custom setups
   For users relying on the recommended build setups/templates in this project, is linking to weak-node-api already handled for them, or do you expect addon authors to add the link dependency manually?

   • If templates handle it, I’ll phrase it as: “If you use the provided templates, you’re covered; custom setups must ensure they link against weak-node-api.”
   • If not, I’ll make the requirement more explicit and concrete.

4. How specific about library naming?
   Do you want docs/PREBUILDS.md to mention any canonical library / framework names per platform, or should it stay higher-level (e.g. “link your addon against the weak-node-api library shipped by react-native-node-api”) and leave exact names to platform-specific build docs?

5. Troubleshooting section
   Would you like a small troubleshooting note (e.g. “undefined napi_* symbols → check you’re linking against weak-node-api”), or should PREBUILDS.md stay strictly about structure and requirements?

---

High-level plan for docs changes

Assuming the above, here’s how I’d approach the PR:

1. Update docs/PREBUILDS.md: add a “Linking against `weak-node-api`” section

   • Explicitly state that prebuilt Node-API modules for React Native must link against weak-node-api (with platform scope per your answer).
   • Briefly explain why (addons depend only on the Node-API surface; the host/Hermes provide the implementation at runtime).
   • Mention how this interacts with the recommended build tooling (templates vs. custom setups).
   • Link to the weak-node-api README for background.

2. Update weak-node-api/README.md: add a short “Usage with React Native prebuilds” subsection

   • Note that addons targeting React Native should link against weak-node-api rather than directly against Hermes / host symbols.
   • Point readers to docs/PREBUILDS.md for the prebuild naming and directory structure.

3. (Optional) Add a troubleshooting snippet in docs/PREBUILDS.md

   • Add a short note for common symbol/link errors and direct people to verify that their prebuilds are correctly linked against weak-node-api.

If this direction looks good, I’ll go ahead and implement it according to your answers.

[kraenhansen]

Actually, in the context of nodejs/node#60916 (comment) I think we should hold back on solving this issue for now.

[reckziegelwilliam]

@kraenhansen seems like progress has been made on this...? Otherwise, does hold also apply to example app as well?Contribute an Expo Example App #156

[kraenhansen]

Sorry for the wait here - I think it would make sense to hold back on both this and #156 as I expect things will be shifting quite a bit this year. I'll update this issue when it stabilise a bit more.

Thanks again for your interest in improving this! Please consider joining the "react-native-node-api" on Callstack's discord to follow along and share any ideas you might have 💙