Add docs on weak-node-api #221

Activity

1. kraenhansen

   self-assigned this

   on Aug 15, 2025
2. kraenhansen

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   good first issueGood for newcomersGood for newcomers

   on Aug 15, 2025
3. reckziegelwilliam commented on Nov 30, 2025

   

   reckziegelwilliam

   on Nov 30, 2025

   More actions

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

   👍React with 👍1Reacted by Kræn Hansen
4. kraenhansen commented on Nov 30, 2025

   

   kraenhansen

   on Nov 30, 2025

   Last edited by kraenhansen

   CollaboratorAuthor

   More actions

   @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.
5. reckziegelwilliam commented on Nov 30, 2025

   

   reckziegelwilliam

   on Nov 30, 2025

   More actions

   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.
6. kraenhansen commented on Dec 1, 2025

   

   kraenhansen

   on Dec 1, 2025

   CollaboratorAuthor

   More actions

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

   👍React with 👍2Reacted by Liam and Jamie Birch
7. reckziegelwilliam commented on Dec 8, 2025

   

   reckziegelwilliam

   on Dec 8, 2025

   More actions

   @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
8. kraenhansen commented on Jan 14, 2026

   

   kraenhansen

   on Jan 14, 2026

   Last edited by kraenhansen

   CollaboratorAuthor

   More actions

   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 💙
9. kraenhansen

   removed

   good first issueGood for newcomersGood for newcomers

   on Jan 14, 2026