@rejaul/react-native-rust 1.1.1 → 2.0.0

package/README.md

@@ -19,6 +19,7 @@ The generated [`react-native-awesome-library-example`](react-native-awesome-libr
 - [Create a library](#create-a-library)
 - [Add Rust functions](#add-rust-functions)
 - [Use Rust in an app](#use-rust-in-an-app)
+- [Automatic development mode](#automatic-development-mode)
 - [Build and run](#build-and-run)
 - [Supported types](#supported-types)
 - [Publish](#publish)
@@ -109,9 +110,20 @@ npx react-native-rust init --app
 npm install
 ```
 
-The command creates a private local TurboModule package in `native/rust-module/`, adds it to the app as a local dependency, and generates its C++ bridge and Rust crate. It does not publish a separate library. App-local mode currently supports C++ TurboModule apps with both Android and iOS projects.
+The command creates a private local TurboModule package in `.rust-native/` (hidden, generated C++/TurboModule glue only — never hand-edit it), and puts the Rust crate itself at the app's own root, `rust/`, alongside `android/` and `ios/`. It adds `.rust-native/` to the app as a local dependency and generates its C++ bridge. It does not publish a separate library. App-local mode currently supports C++ TurboModule apps with both Android and iOS projects.
 
-Edit `native/rust-module/src/NativeRustApp.ts` to declare methods, then implement their generated handlers under `native/rust-module/rust/src/api/`. From the app root, regenerate the bindings and React Native Codegen output with:
+```
+my-app/
+├── rust/                ← edit this: your Rust crate
+│   ├── Cargo.toml
+│   └── src/api/
+├── .rust-native/         ← generated TurboModule glue; do not edit
+├── android/
+├── ios/
+└── package.json
+```
+
+Edit `.rust-native/src/NativeRustApp.ts` to declare methods, then implement their generated handlers under `rust/src/api/`. From the app root, regenerate the bindings and React Native Codegen output with:
 
 ```sh
 npm run rust:generate
@@ -134,6 +146,44 @@ npx react-native run-ios
 
 The generated module is app-local and can be used from the app's JavaScript imports. The root `example/` project in this repository exercises this workflow.
 
+## Automatic development mode
+
+The commands above (`rust:generate`, `rust:build:*`) still work exactly as before and remain fully supported. For day-to-day development, `react-native-rust watch` runs instead, watching the `Spec` and `rust/` and reacting automatically:
+
+```
+Legacy workflow:  init → generate → build (repeated by hand after every change)
+New workflow:     init once → npx react-native-rust watch (or npx react-native start, with Metro integration below)
+```
+
+On every save, the watcher classifies the change and reacts accordingly, matching what a manual run of `generate`/`build` would already produce:
+
+- **A Rust file under `rust/src/`, or `Cargo.toml`/`Cargo.lock`, changes** (an implementation-only edit): it runs an incremental `cargo build` only. Native bindings are not regenerated.
+- **The `Spec` file changes** (a new method, or a signature change): it runs `generate()` first — preserving hand-written Rust handler bodies, exactly like running `rust:generate` by hand — and then `cargo build`.
+- Rapid successive saves are debounced and coalesced into one build; a build already in progress is never interrupted, and at most one more run is queued behind it.
+- A failed build or a failed code generation prints the error and keeps watching; it does not crash the process or leave stale generated files.
+
+Run it directly:
+
+```sh
+npx react-native-rust watch
+```
+
+Or wire it into Metro so `npx react-native start` runs it automatically:
+
+```js
+// metro.config.js
+const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
+const { withRust } = require('@rejaul/react-native-rust/metro');
+
+module.exports = withRust(mergeConfig(getDefaultConfig(__dirname), {}));
+```
+
+`withRust()` detects your Rust project automatically at `rust/` (both library mode and app-local mode keep it at the project root) and adds it to `watchFolders`; pass `{ rustDir: './rust' }` only if your Rust project lives somewhere non-standard. It starts the watcher only while Metro's dev server is actually serving requests — never during a production/release bundle — and its `[Rust]`/`[RN Rust]` output streams into the same terminal as Metro's own. If Rust hasn't been initialized yet, it no-ops with a one-line notice instead of erroring, so it's safe to add before running `init`.
+
+If Metro integration isn't wired up (or doesn't fit your setup), run `npx react-native-rust watch` in a separate terminal alongside `npx react-native start` — it does the same thing standalone.
+
+**What this does not do:** Rust and C++ are native code. A running Android/iOS app cannot hot-swap a rebuilt native library the way Metro hot-swaps JavaScript. Each cycle rebuilds the Rust crate and prints a reminder that you still need to run `npm run rust:build:ios` / `rust:build:android` and reinstall the app to load the change on a simulator or device. A `Spec` change also regenerates `src/rust-generated.native.tsx`, which Metro's own JS watcher will pick up and Fast Refresh on its own, same as any other JS/TS change.
+
 ## Build and run
 
 Run these commands from the library root. Generate TurboModule Codegen output with `yarn prepare` before building the host app.
@@ -271,6 +321,9 @@ Pushing a version tag such as `v1.0.2` runs [`.github/workflows/publish.yml`](.g
 - `wasm-pack: command not found`: install it with `cargo install wasm-pack`, or run `react-native-rust doctor web` to check both prerequisites.
 - The web app throws "Call and await initRustWeb()...": await `initRustWeb()` once before calling any other generated function; loading the `.wasm` file is asynchronous even though the generated calls are not.
 - A React Native type is reported as unsupported: check the mappings and signature restrictions in [Supported types](#supported-types).
+- `react-native-rust watch` prints "Rust is not initialized": run `react-native-rust init` (or `init --app`) first; the watcher requires `rust/Cargo.toml` to exist.
+- Changes made in a running app never appear, even after "`[Rust] Build completed`": native code cannot hot-swap into a running process. Run `npm run rust:build:ios` / `rust:build:android` and reinstall the app, as [Automatic development mode](#automatic-development-mode) describes.
+- `npx react-native start` doesn't print any `[Rust]` lines: confirm `metro.config.js` calls `withRust(...)` and that `rust/Cargo.toml` exists at the project root; otherwise run `npx react-native-rust watch` in a separate terminal.
 
 ## Contributing
 

package/dist/app.js

@@ -38,7 +38,7 @@ var import_node_fs = __toESM(require("node:fs"));
 var import_node_path = __toESM(require("node:path"));
 var import_node_child_process = require("node:child_process");
 var import_react_native_rust_lib = require("./react-native-rust-lib");
-const moduleDirectory = import_node_path.default.join("native", "rust-module");
+const moduleDirectory = ".rust-native";
 const moduleName = "RustApp";
 const packageName = "rust-app-native-module";
 function writeFiles(root, files) {
@@ -58,7 +58,7 @@ function scaffoldFiles(appName) {
       main: "src/index.tsx",
       "react-native": "src/index.tsx",
       types: "src/index.tsx",
-      files: ["src/", "cpp/", "android/", "ios/", "*.podspec", "react-native.config.js", "rust/"],
+      files: ["src/", "cpp/", "android/", "ios/", "*.podspec", "react-native.config.js"],
       peerDependencies: { react: "*", "react-native": ">=0.76" },
       codegenConfig: {
         name: `${moduleName}Spec`,
@@ -67,7 +67,9 @@ function scaffoldFiles(appName) {
         outputDir: { ios: "ios/generated", android: "android/generated" },
         android: { javaPackageName },
         includesGeneratedCode: true
-      }
+      },
+      // The Rust crate lives at the app's own root, not inside this generated module package.
+      reactNativeRust: { rustDir: "../rust" }
     }, null, 2)}
 `,
     "react-native.config.js": `module.exports = {
@@ -93,11 +95,13 @@ function scaffoldFiles(appName) {
   s.source = { :git => "https://example.invalid" }
   s.platforms = { :ios => min_ios_version_supported }
   s.source_files = "cpp/**/*.{hpp,cpp,c,h}", "ios/**/*.{h,m,mm}", "ios/generated/*.{h,cpp,mm}"
-  s.vendored_frameworks = "rust/build/ios/${moduleName}Rust.xcframework"
   install_modules_dependencies(s)
 end
 `,
-    ".gitignore": "node_modules/\nrust/target/\nrust/build/\n",
+    // rust-include, rust-build-android, rust-build-ios: generated by `init`/`build` to reach
+    // the Rust crate at the app's own root (see resolveOutsideReference) — a real symlink or, for
+    // iOS, a copied build artifact, never hand-authored.
+    ".gitignore": "node_modules/\nrust-include\nrust-build-android\nrust-build-ios\nrust-build-web-pkg\n",
     "src/NativeRustApp.ts": `import { TurboModuleRegistry, type TurboModule } from 'react-native';
 
 export interface Spec extends TurboModule {
@@ -188,7 +192,8 @@ using namespace facebook::react;
 }
 function appModuleRoot(appRoot = process.cwd()) {
   const moduleRoot = import_node_path.default.join(appRoot, moduleDirectory);
-  return import_node_fs.default.existsSync(import_node_path.default.join(moduleRoot, "rust", "Cargo.toml")) ? moduleRoot : null;
+  if (!import_node_fs.default.existsSync(import_node_path.default.join(moduleRoot, "package.json"))) return null;
+  return import_node_fs.default.existsSync(import_node_path.default.join(appRoot, "rust", "Cargo.toml")) ? moduleRoot : null;
 }
 function inDirectory(directory, callback) {
   const previousDirectory = process.cwd();
@@ -250,16 +255,25 @@ function initApp() {
       "rust:generate": "react-native-rust generate",
       "rust:build:ios": "react-native-rust build ios",
       "rust:build:android": "react-native-rust build android",
-      "rust:test": `cargo test --manifest-path ${moduleDirectory.split(import_node_path.default.sep).join("/")}/rust/Cargo.toml`
+      "rust:test": "cargo test --manifest-path rust/Cargo.toml"
     };
     runCodegen(appRoot, moduleRoot);
     import_node_fs.default.writeFileSync(appManifestPath, `${JSON.stringify(appManifest, null, 2)}
 `);
+    const gitignorePath = import_node_path.default.join(appRoot, ".gitignore");
+    const gitignore = import_node_fs.default.existsSync(gitignorePath) ? import_node_fs.default.readFileSync(gitignorePath, "utf8") : "";
+    const ignoredRustOutputs = ["rust/target/", "rust/build/"].filter((entry) => !gitignore.split(/\r?\n/).includes(entry));
+    if (ignoredRustOutputs.length > 0) {
+      const separator = gitignore.length > 0 && !gitignore.endsWith("\n") ? "\n" : "";
+      import_node_fs.default.writeFileSync(gitignorePath, `${gitignore}${separator}${ignoredRustOutputs.join("\n")}
+`);
+    }
   } catch (error) {
     import_node_fs.default.rmSync(moduleRoot, { recursive: true, force: true });
+    import_node_fs.default.rmSync(import_node_path.default.join(appRoot, "rust"), { recursive: true, force: true });
     throw error;
   }
-  console.log(`Created app-local Rust TurboModule in ${import_node_path.default.relative(appRoot, moduleRoot)}.`);
+  console.log("Created app-local Rust TurboModule: edit rust/src/api/, glue lives in .rust-native/ (generated, do not edit).");
   console.log("Install app dependencies, then run `npm run rust:build:android` or `npm run rust:build:ios`.");
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/codegen/index.js

@@ -20,7 +20,9 @@ var codegen_exports = {};
 __export(codegen_exports, {
   parseSpec: () => import_spec.parseSpec,
   renderProjectBindings: () => import_project.renderProjectBindings,
-  renderRustFfiModule: () => import_renderers.renderRustFfiModule
+  renderRustFfiModule: () => import_renderers.renderRustFfiModule,
+  resolveOutsideReference: () => import_project.resolveOutsideReference,
+  toPosixRelative: () => import_project.toPosixRelative
 });
 module.exports = __toCommonJS(codegen_exports);
 var import_spec = require("./spec");
@@ -30,5 +32,7 @@ var import_project = require("./project");
 0 && (module.exports = {
   parseSpec,
   renderProjectBindings,
-  renderRustFfiModule
+  renderRustFfiModule,
+  resolveOutsideReference,
+  toPosixRelative
 });

package/dist/codegen/project.js

@@ -33,6 +33,8 @@ __export(project_exports, {
   renderProjectBindings: () => renderProjectBindings,
   replaceMarkedRegion: () => replaceMarkedRegion,
   replaceTemplateMethod: () => replaceTemplateMethod,
+  resolveOutsideReference: () => resolveOutsideReference,
+  toPosixRelative: () => toPosixRelative,
   updateCppFile: () => updateCppFile,
   validateExistingHandler: () => validateExistingHandler
 });
@@ -41,6 +43,16 @@ var import_node_fs = __toESM(require("node:fs"));
 var import_node_path = __toESM(require("node:path"));
 var import_constants = require("./constants");
 var import_renderers = require("./renderers");
+function toPosixRelative(from, to) {
+  return import_node_path.default.relative(from, to).split(import_node_path.default.sep).join("/");
+}
+function resolveOutsideReference(root, targetDir, linkName) {
+  if (!toPosixRelative(root, targetDir).startsWith("..")) return targetDir;
+  const linkPath = import_node_path.default.join(root, linkName);
+  import_node_fs.default.rmSync(linkPath, { force: true });
+  import_node_fs.default.symlinkSync(toPosixRelative(root, targetDir), linkPath);
+  return linkPath;
+}
 function replaceMarkedRegion(source, startMarker, endMarker, generated) {
   const start = source.indexOf(startMarker);
   const end = source.indexOf(endMarker);
@@ -91,11 +103,13 @@ function hasDefaultMultiplyBody(source, moduleName) {
   }
   return false;
 }
-function updateCppFile(source, markers, generated, templateMethod, methodNeedle, includeRustHeader = false) {
+function updateCppFile(source, markers, generated, templateMethod, methodNeedle, rustHeaderPath) {
   let updated = source;
-  if (includeRustHeader && !updated.includes("../rust/include/rust_api.h")) {
+  if (rustHeaderPath && !updated.includes(`#include "${rustHeaderPath}"`)) {
     if (!updated.includes("#pragma once")) throw new Error("Unsupported C++ module header template.");
-    updated = updated.replace("#pragma once", '#pragma once\n\n#include "../rust/include/rust_api.h"');
+    updated = updated.replace("#pragma once", `#pragma once
+
+#include "${rustHeaderPath}"`);
   }
   const marked = replaceMarkedRegion(updated, markers[0], markers[1], generated);
   if (marked !== null) return marked;
@@ -132,7 +146,7 @@ function validateExistingHandler(filePath, method) {
     throw new Error(`Rust handler ${import_node_path.default.relative(process.cwd(), filePath)} does not match the TypeScript Spec. Update its signature before regenerating.`);
   }
 }
-function renderProjectBindings(root, moduleName, methods, initialize, crateName) {
+function renderProjectBindings(root, moduleName, methods, initialize, crateName, rustRoot = import_node_path.default.join(root, "rust")) {
   const headerPath = import_node_path.default.join(root, "cpp", `${moduleName}Impl.h`);
   const sourcePath = import_node_path.default.join(root, "cpp", `${moduleName}Impl.cpp`);
   const header = import_node_fs.default.readFileSync(headerPath, "utf8");
@@ -145,7 +159,9 @@ function renderProjectBindings(root, moduleName, methods, initialize, crateName)
   const cppSource = cpp.source.replace(/^#include .+\n/gm, "");
   const headerTemplateMethod = "double multiply(jsi::Runtime& rt, double a, double b);";
   const sourceTemplateMethod = `${moduleName}Impl::multiply(`;
-  const updatedHeader = updateCppFile(header, [import_constants.HEADER_START, import_constants.HEADER_END], cpp.header, initialize, headerTemplateMethod, true);
+  const rustIncludeTarget = resolveOutsideReference(root, import_node_path.default.join(rustRoot, "include"), "rust-include");
+  const rustHeaderPath = `${toPosixRelative(import_node_path.default.join(root, "cpp"), rustIncludeTarget)}/rust_api.h`;
+  const updatedHeader = updateCppFile(header, [import_constants.HEADER_START, import_constants.HEADER_END], cpp.header, initialize, headerTemplateMethod, rustHeaderPath);
   let updatedSource = updateCppFile(source, [import_constants.SOURCE_START, import_constants.SOURCE_END], cppSource, initialize, sourceTemplateMethod);
   if (generatedIncludes.length > 0) {
     const namespaceIndex = updatedSource.indexOf("\nnamespace facebook::react {");
@@ -157,7 +173,7 @@ function renderProjectBindings(root, moduleName, methods, initialize, crateName)
 ${updatedSource.slice(insertionPoint)}`;
     }
   }
-  const rustDirectory = import_node_path.default.join(root, "rust", "src");
+  const rustDirectory = import_node_path.default.join(rustRoot, "src");
   const moduleList = (0, import_renderers.renderRustModuleList)(methods);
   const updates = /* @__PURE__ */ new Map([
     [headerPath, updatedHeader],
@@ -171,7 +187,9 @@ ${updatedSource.slice(insertionPoint)}`;
     if (import_node_fs.default.existsSync(handlerPath)) validateExistingHandler(handlerPath, method);
     else updates.set(handlerPath, (0, import_renderers.renderRustHandler)(method));
   }
-  const wrappers = (0, import_renderers.renderWrappers)(methods, moduleName, crateName);
+  const wasmPkgTarget = resolveOutsideReference(root, import_node_path.default.join(rustRoot, "build", "web", "pkg"), "rust-build-web-pkg");
+  const wasmPkgPath = toPosixRelative(import_node_path.default.join(root, "src"), wasmPkgTarget);
+  const wrappers = (0, import_renderers.renderWrappers)(methods, moduleName, crateName, wasmPkgPath);
   const generatedModulePath = import_node_path.default.join(root, "src", "rust-generated");
   updates.set(`${generatedModulePath}.tsx`, wrappers.web);
   updates.set(`${generatedModulePath}.native.tsx`, wrappers.native);
@@ -196,6 +214,8 @@ export * from './rust-generated';
   renderProjectBindings,
   replaceMarkedRegion,
   replaceTemplateMethod,
+  resolveOutsideReference,
+  toPosixRelative,
   updateCppFile,
   validateExistingHandler
 });

package/dist/codegen/renderers.js

@@ -391,7 +391,7 @@ function renderCppMethods(methods, moduleName) {
 ${definitions.join("\n\n")}`
   };
 }
-function renderWrappers(methods, moduleName, crateName) {
+function renderWrappers(methods, moduleName, crateName, wasmPkgPath = "../rust/build/web/pkg") {
   const nativeLines = [
     `import ${moduleName} from './Native${moduleName}';`,
     "",
@@ -402,7 +402,7 @@ function renderWrappers(methods, moduleName, crateName) {
     ""
   ];
   const webLines = [
-    `import wasmInit, * as rnrsWasm from '../rust/build/web/pkg/${crateName}.js';`,
+    `import wasmInit, * as rnrsWasm from '${wasmPkgPath}/${crateName}.js';`,
     "",
     "let rnrsWasmReady = false;",
     "let rnrsWasmInit: Promise<void> | null = null;",

package/dist/dev/buildQueue.js

@@ -0,0 +1,54 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var buildQueue_exports = {};
+__export(buildQueue_exports, {
+  SingleFlightQueue: () => SingleFlightQueue
+});
+module.exports = __toCommonJS(buildQueue_exports);
+class SingleFlightQueue {
+  constructor(task) {
+    this.task = task;
+  }
+  task;
+  running = false;
+  pending = false;
+  /** Requests a run. Coalesced into the in-flight run's follow-up if one is already running. */
+  request() {
+    if (this.running) {
+      this.pending = true;
+      return;
+    }
+    void this.run();
+  }
+  async run() {
+    this.running = true;
+    do {
+      this.pending = false;
+      try {
+        await this.task();
+      } catch {
+      }
+    } while (this.pending);
+    this.running = false;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SingleFlightQueue
+});

package/dist/dev/watcher.js

@@ -0,0 +1,90 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var watcher_exports = {};
+__export(watcher_exports, {
+  classifyChange: () => classifyChange,
+  watchRustProject: () => watchRustProject
+});
+module.exports = __toCommonJS(watcher_exports);
+var import_node_path = __toESM(require("node:path"));
+var import_chokidar = __toESM(require("chokidar"));
+function classifyChange(filePath, target) {
+  const resolved = import_node_path.default.resolve(filePath);
+  if (resolved === import_node_path.default.resolve(target.specPath)) return "spec";
+  const rustSrc = import_node_path.default.resolve(target.rustRoot, "src");
+  const cargoToml = import_node_path.default.resolve(target.rustRoot, "Cargo.toml");
+  const cargoLock = import_node_path.default.resolve(target.rustRoot, "Cargo.lock");
+  if (resolved === cargoToml || resolved === cargoLock) return "rust";
+  if (resolved.startsWith(`${rustSrc}${import_node_path.default.sep}`) && resolved.endsWith(".rs")) return "rust";
+  return "other";
+}
+function watchRustProject(options) {
+  const { target, onChange, debounceMs = 200, log = console.log } = options;
+  const watcher = import_chokidar.default.watch(
+    [import_node_path.default.join(target.rustRoot, "**", "*.rs"), import_node_path.default.join(target.rustRoot, "Cargo.toml"), import_node_path.default.join(target.rustRoot, "Cargo.lock"), target.specPath],
+    {
+      ignored: [
+        import_node_path.default.join(target.rustRoot, "target", "**"),
+        import_node_path.default.join(target.rustRoot, "build", "**"),
+        import_node_path.default.join(target.rustRoot, "include", "**"),
+        "**/node_modules/**",
+        "**/.git/**"
+      ],
+      ignoreInitial: true,
+      // Waits for a file's size to stop changing before firing, so editors that write in
+      // multiple chunks (atomic saves, rename-into-place) produce one event, not several.
+      awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 20 }
+    }
+  );
+  let pendingKinds = /* @__PURE__ */ new Set();
+  let timer = null;
+  const schedule = (filePath, eventLabel) => {
+    const kind = classifyChange(filePath, target);
+    if (kind === "other") return;
+    pendingKinds.add(kind);
+    log(`[Rust] ${eventLabel} ${import_node_path.default.relative(import_node_path.default.dirname(target.rustRoot), filePath)}`);
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      const kinds = pendingKinds;
+      pendingKinds = /* @__PURE__ */ new Set();
+      timer = null;
+      onChange(kinds);
+    }, debounceMs);
+  };
+  watcher.on("add", (filePath) => schedule(filePath, "Added"));
+  watcher.on("change", (filePath) => schedule(filePath, "Changed"));
+  watcher.on("unlink", (filePath) => schedule(filePath, "Deleted"));
+  watcher.on("error", (error) => log(`[Rust] Watcher error: ${error.message}`));
+  return watcher;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  classifyChange,
+  watchRustProject
+});

package/dist/metro.js

@@ -0,0 +1,100 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var metro_exports = {};
+__export(metro_exports, {
+  findRustDir: () => findRustDir,
+  stopRustWatcher: () => stopRustWatcher,
+  withRust: () => withRust
+});
+module.exports = __toCommonJS(metro_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_child_process = require("node:child_process");
+let watcherProcess = null;
+function findRustDir(projectRoot, rustDir) {
+  const resolved = import_node_path.default.resolve(projectRoot, rustDir || "rust");
+  return import_node_fs.default.existsSync(import_node_path.default.join(resolved, "Cargo.toml")) ? resolved : null;
+}
+function ensureWatcherRunning(projectRoot, notify) {
+  if (watcherProcess) return;
+  const cliEntry = import_node_path.default.join(__dirname, "react-native-rust.js");
+  const child = (0, import_node_child_process.spawn)(process.execPath, [cliEntry, "watch"], { cwd: projectRoot });
+  watcherProcess = child;
+  child.stdout?.on("data", (chunk) => process.stdout.write(chunk));
+  child.stderr?.on("data", (chunk) => process.stderr.write(chunk));
+  child.on("exit", (code) => {
+    watcherProcess = null;
+    if (code !== 0 && code !== null) {
+      notify(`[RN Rust] The Rust watcher exited unexpectedly (code ${code}). Restart Metro to retry, or run \`npx react-native-rust watch\` manually.`);
+    }
+  });
+  const stop = () => {
+    if (watcherProcess) watcherProcess.kill("SIGINT");
+  };
+  process.once("exit", stop);
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+}
+function stopRustWatcher() {
+  if (!watcherProcess) return Promise.resolve();
+  const child = watcherProcess;
+  return new Promise((resolve) => {
+    child.once("exit", () => resolve());
+    child.kill("SIGINT");
+  });
+}
+function withRust(config, options = {}) {
+  const projectRoot = config.projectRoot || process.cwd();
+  const rustDir = findRustDir(projectRoot, options.rustDir);
+  const existingWatchFolders = config.watchFolders || [];
+  const watchFolders = rustDir && !existingWatchFolders.includes(rustDir) ? [...existingWatchFolders, rustDir] : existingWatchFolders;
+  const previousEnhanceMiddleware = config.server?.enhanceMiddleware;
+  return {
+    ...config,
+    watchFolders,
+    server: {
+      ...config.server,
+      enhanceMiddleware: (middleware, server) => {
+        const next = previousEnhanceMiddleware ? previousEnhanceMiddleware(middleware, server) : middleware;
+        if (rustDir) {
+          ensureWatcherRunning(projectRoot, console.log);
+        } else {
+          console.log("[RN Rust] No rust/Cargo.toml found; skipping the automatic Rust watcher. Run `npx react-native-rust init` (or `init --app`) to add Rust support.");
+        }
+        return next;
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findRustDir,
+  stopRustWatcher,
+  withRust
+});

package/dist/react-native-rust-lib.js

@@ -34,13 +34,16 @@ __export(react_native_rust_lib_exports, {
   init: () => init,
   packageRoot: () => packageRoot,
   readJson: () => readJson,
-  run: () => run
+  run: () => run,
+  watch: () => watch
 });
 module.exports = __toCommonJS(react_native_rust_lib_exports);
 var import_node_fs = __toESM(require("node:fs"));
 var import_node_path = __toESM(require("node:path"));
 var import_node_child_process = require("node:child_process");
 var import_codegen = require("./codegen");
+var import_watcher = require("./dev/watcher");
+var import_buildQueue = require("./dev/buildQueue");
 const rustDirectory = "rust";
 const iosTargets = ["aarch64-apple-ios", "aarch64-apple-ios-sim", "x86_64-apple-ios"];
 const androidTargets = [
@@ -93,6 +96,9 @@ function packageRoot() {
   }
   return { root, manifest, manifestPath, moduleName: moduleMatch[1] };
 }
+function resolveRustRoot(root, manifest) {
+  return import_node_path.default.resolve(root, manifest.reactNativeRust?.rustDir || rustDirectory);
+}
 function readCrateName(rustRoot) {
   const manifestPath = import_node_path.default.join(rustRoot, "Cargo.toml");
   const cargoManifest = import_node_fs.default.readFileSync(manifestPath, "utf8");
@@ -102,9 +108,9 @@ function readCrateName(rustRoot) {
 }
 function init() {
   const { root, manifest, manifestPath, moduleName } = packageRoot();
-  const rustPath = import_node_path.default.join(root, rustDirectory);
+  const rustPath = resolveRustRoot(root, manifest);
   if (import_node_fs.default.existsSync(rustPath)) {
-    throw new Error("The rust/ directory already exists; no files were changed.");
+    throw new Error(`${import_node_path.default.relative(root, rustPath) || "rust"}/ already exists; no files were changed.`);
   }
   const scripts = manifest.scripts || {};
   if (scripts["rust:test"] || scripts["rust:generate"]) {
@@ -145,19 +151,22 @@ function init() {
     dl
     m
 )`;
+  const androidRustBuildTarget = (0, import_codegen.resolveOutsideReference)(root, import_node_path.default.join(rustPath, "build", "android"), "rust-build-android");
+  const androidRustBuildPath = (0, import_codegen.toPosixRelative)(import_node_path.default.join(root, "android"), androidRustBuildTarget);
   const rustImport = `add_library(rust_core STATIC IMPORTED)
 set_target_properties(rust_core PROPERTIES
-    IMPORTED_LOCATION "\${CMAKE_CURRENT_LIST_DIR}/../rust/build/android/\${ANDROID_ABI}/lib${crateDirName}.a"
+    IMPORTED_LOCATION "\${CMAKE_CURRENT_LIST_DIR}/${androidRustBuildPath}/\${ANDROID_ABI}/lib${crateDirName}.a"
 )
 
 `;
   const androidCmake = contents.androidCmake.replace(linkMatch[0], androidLink).replace(/add_library\(/, `${rustImport}add_library(`);
   const podspecSource = contents.podspec.match(/^\s*s\.source_files\s*=.*$/m);
   if (!podspecSource) throw new Error("Could not locate source_files in the CocoaPods spec.");
+  const iosRustBuildPath = (0, import_codegen.toPosixRelative)(root, import_node_path.default.join(rustPath, "build", "ios")).startsWith("..") ? "rust-build-ios" : (0, import_codegen.toPosixRelative)(root, import_node_path.default.join(rustPath, "build", "ios"));
   const podspec = contents.podspec.replace(
     podspecSource[0],
     `${podspecSource[0]}
-  s.vendored_frameworks = "rust/build/ios/${moduleName}Rust.xcframework"`
+  s.vendored_frameworks = "${iosRustBuildPath}/${moduleName}Rust.xcframework"`
   );
   const rustFiles = {
     "Cargo.toml": `[package]
@@ -200,7 +209,7 @@ Rust handlers are generated from the TurboModule Spec interface in src/Native${m
 Run cargo test --manifest-path rust/Cargo.toml for Rust tests. Build iOS and Android artifacts with npx react-native-rust build ios and npx react-native-rust build android before native app builds. Build the react-native-web WebAssembly package with npx react-native-rust build web (requires wasm-pack and the wasm32-unknown-unknown Rust target).
 `
   };
-  const updates = (0, import_codegen.renderProjectBindings)(root, moduleName, methods, true, crateDirName);
+  const updates = (0, import_codegen.renderProjectBindings)(root, moduleName, methods, true, crateDirName, rustPath);
   updates.set(projectFiles.androidCmake, androidCmake);
   updates.set(projectFiles.podspec, podspec);
   const cliManifest = readJson(import_node_path.default.join(__dirname, "..", "package.json"));
@@ -215,27 +224,32 @@ Run cargo test --manifest-path rust/Cargo.toml for Rust tests. Build iOS and And
     },
     scripts: {
       ...scripts,
-      "rust:test": "cargo test --manifest-path rust/Cargo.toml",
+      "rust:test": `cargo test --manifest-path ${(0, import_codegen.toPosixRelative)(root, rustPath)}/Cargo.toml`,
       "rust:generate": "react-native-rust generate",
       "rust:build:ios": "react-native-rust build ios",
       "rust:build:android": "react-native-rust build android",
       "rust:build:web": "react-native-rust build web"
     }
   };
-  const packageFiles = Array.isArray(updatedManifest.files) ? [...updatedManifest.files] : [];
-  for (const filePath of ["rust/", "rust/build/", "rust/include/"]) {
-    if (!packageFiles.includes(filePath)) packageFiles.push(filePath);
+  const rustIsInsideRoot = !(0, import_codegen.toPosixRelative)(root, rustPath).startsWith("..");
+  if (rustIsInsideRoot) {
+    const packageFiles = Array.isArray(updatedManifest.files) ? [...updatedManifest.files] : [];
+    for (const filePath of ["rust/", "rust/build/", "rust/include/"]) {
+      if (!packageFiles.includes(filePath)) packageFiles.push(filePath);
+    }
+    updatedManifest.files = packageFiles;
   }
-  updatedManifest.files = packageFiles;
   updates.set(manifestPath, `${JSON.stringify(updatedManifest, null, 2)}
 `);
-  const gitignorePath = import_node_path.default.join(root, ".gitignore");
-  const gitignore = import_node_fs.default.existsSync(gitignorePath) ? import_node_fs.default.readFileSync(gitignorePath, "utf8") : "";
-  const ignoredRustOutputs = ["rust/target/", "rust/build/"].filter((entry) => !gitignore.split(/\r?\n/).includes(entry));
-  if (ignoredRustOutputs.length > 0) {
-    const separator = gitignore.length > 0 && !gitignore.endsWith("\n") ? "\n" : "";
-    updates.set(gitignorePath, `${gitignore}${separator}${ignoredRustOutputs.join("\n")}
+  if (rustIsInsideRoot) {
+    const gitignorePath = import_node_path.default.join(root, ".gitignore");
+    const gitignore = import_node_fs.default.existsSync(gitignorePath) ? import_node_fs.default.readFileSync(gitignorePath, "utf8") : "";
+    const ignoredRustOutputs = ["rust/target/", "rust/build/"].filter((entry) => !gitignore.split(/\r?\n/).includes(entry));
+    if (ignoredRustOutputs.length > 0) {
+      const separator = gitignore.length > 0 && !gitignore.endsWith("\n") ? "\n" : "";
+      updates.set(gitignorePath, `${gitignore}${separator}${ignoredRustOutputs.join("\n")}
 `);
+    }
   }
   for (const [relativePath, fileContents] of Object.entries(rustFiles)) {
     const outputPath = import_node_path.default.join(rustPath, relativePath);
@@ -250,14 +264,14 @@ Run cargo test --manifest-path rust/Cargo.toml for Rust tests. Build iOS and And
   console.log("Run `npx react-native-rust build ios` or `npx react-native-rust build android` before building the React Native app.");
 }
 function generate() {
-  const { root, moduleName } = packageRoot();
-  const rustPath = import_node_path.default.join(root, rustDirectory);
+  const { root, manifest, moduleName } = packageRoot();
+  const rustPath = resolveRustRoot(root, manifest);
   if (!import_node_fs.default.existsSync(import_node_path.default.join(rustPath, "Cargo.toml"))) {
     throw new Error("Rust is not initialized. Run `npx react-native-rust init` first.");
   }
   const nativeSpecPath = import_node_path.default.join(root, "src", `Native${moduleName}.ts`);
   const methods = (0, import_codegen.parseSpec)(import_node_fs.default.readFileSync(nativeSpecPath, "utf8"), import_node_path.default.relative(root, nativeSpecPath));
-  const updates = (0, import_codegen.renderProjectBindings)(root, moduleName, methods, false, readCrateName(rustPath));
+  const updates = (0, import_codegen.renderProjectBindings)(root, moduleName, methods, false, readCrateName(rustPath), rustPath);
   for (const [filePath, fileContents] of updates) {
     import_node_fs.default.mkdirSync(import_node_path.default.dirname(filePath), { recursive: true });
     import_node_fs.default.writeFileSync(filePath, fileContents);
@@ -265,8 +279,8 @@ function generate() {
   console.log(`Regenerated Rust, C++, and TypeScript glue for ${methods.length} Spec method(s).`);
 }
 function doctor(target) {
-  const { root } = packageRoot();
-  if (!import_node_fs.default.existsSync(import_node_path.default.join(root, rustDirectory, "Cargo.toml"))) {
+  const { root, manifest } = packageRoot();
+  if (!import_node_fs.default.existsSync(import_node_path.default.join(resolveRustRoot(root, manifest), "Cargo.toml"))) {
     throw new Error("Rust is not initialized. Run `npx react-native-rust init` first.");
   }
   let failed = false;
@@ -301,13 +315,14 @@ function doctor(target) {
 }
 function build(platform) {
   const { root, manifest, moduleName } = packageRoot();
-  const rustRoot = import_node_path.default.join(root, rustDirectory);
+  const rustRoot = resolveRustRoot(root, manifest);
   const manifestPath = import_node_path.default.join(rustRoot, "Cargo.toml");
   if (!import_node_fs.default.existsSync(manifestPath)) {
     throw new Error("Rust is not initialized. Run `npx react-native-rust init` first.");
   }
   const crateName = readCrateName(rustRoot);
   const releasePath = (target) => import_node_path.default.join(rustRoot, "target", target, "release", `lib${crateName}.a`);
+  (0, import_codegen.resolveOutsideReference)(root, import_node_path.default.join(rustRoot, "build", "android"), "rust-build-android");
   if (platform === "ios") {
     for (const target of iosTargets) {
       const result = run("cargo", ["build", "--release", "--target", target, "--manifest-path", manifestPath], { inherit: true });
@@ -342,6 +357,12 @@ function build(platform) {
       frameworkPath
     ], { inherit: true });
     if (!xcframework.ok) throw new Error(`Could not create the iOS XCFramework: ${xcframework.message}`);
+    if ((0, import_codegen.toPosixRelative)(root, frameworkPath).startsWith("..")) {
+      const podFrameworkPath = import_node_path.default.join(root, "rust-build-ios", `${moduleName}Rust.xcframework`);
+      import_node_fs.default.rmSync(import_node_path.default.dirname(podFrameworkPath), { recursive: true, force: true });
+      import_node_fs.default.mkdirSync(import_node_path.default.dirname(podFrameworkPath), { recursive: true });
+      import_node_fs.default.cpSync(frameworkPath, podFrameworkPath, { recursive: true });
+    }
     console.log(`Built ${import_node_path.default.relative(root, frameworkPath)} for ${manifest.name}.`);
     return;
   }
@@ -371,11 +392,71 @@ function build(platform) {
   if (platform === "web") {
     const result = run("wasm-pack", ["build", "--target", "web", "--out-dir", import_node_path.default.join("build", "web", "pkg")], { inherit: true, cwd: rustRoot });
     if (!result.ok) throw new Error(`Web build failed: ${result.message}`);
-    console.log(`Built rust/build/web/pkg for ${manifest.name}.`);
+    console.log(`Built ${(0, import_codegen.toPosixRelative)(root, import_node_path.default.join(rustRoot, "build", "web", "pkg"))} for ${manifest.name}.`);
     return;
   }
   throw new Error("Choose a build target: ios, android, or web.");
 }
+function watch(options = {}) {
+  const { root, manifest, moduleName } = packageRoot();
+  const rustRoot = resolveRustRoot(root, manifest);
+  const cargoManifest = import_node_path.default.join(rustRoot, "Cargo.toml");
+  if (!import_node_fs.default.existsSync(cargoManifest)) {
+    throw new Error("Rust is not initialized. Run `npx react-native-rust init` first.");
+  }
+  const log = options.log || console.log;
+  const target = { rustRoot, specPath: import_node_path.default.join(root, "src", `Native${moduleName}.ts`) };
+  let pendingKinds = /* @__PURE__ */ new Set();
+  async function runWatchCycle(kinds) {
+    if (kinds.has("spec")) {
+      log("[RN Rust] Spec changed. Regenerating native bindings...");
+      try {
+        generate();
+        options.onGenerated?.();
+      } catch (error) {
+        log("[RN Rust] Code generation failed.");
+        log("Possible causes:");
+        log("  - invalid Rust API");
+        log("  - unsupported parameter type");
+        log("  - unsupported return type");
+        log("  - invalid annotation/spec");
+        log(`  ${error.message}`);
+        log("[Rust] Waiting for changes...");
+        return;
+      }
+      log("[RN Rust] Native bindings updated.");
+    }
+    log("[Rust] Building...");
+    const start = Date.now();
+    const result = run("cargo", ["build", "--manifest-path", cargoManifest], { inherit: true });
+    const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
+    if (!result.ok) {
+      log("[Rust] Build failed.");
+      log("[Rust] Waiting for changes...");
+      return;
+    }
+    log(`[Rust] Build completed in ${elapsed}s`);
+    log("[Rust] Native library updated.");
+    log("[RN Rust] Native code cannot hot-swap into a running app: run `npm run rust:build:ios` / `rust:build:android` / `rust:build:web` and reinstall (or refresh the browser tab, for react-native-web) to load this change.");
+    log("[Rust] Waiting for changes...");
+  }
+  const queue = new import_buildQueue.SingleFlightQueue(() => {
+    const kinds = pendingKinds;
+    pendingKinds = /* @__PURE__ */ new Set();
+    return runWatchCycle(kinds);
+  });
+  const watcher = (0, import_watcher.watchRustProject)({
+    target,
+    log,
+    onChange: (kinds) => {
+      for (const kind of kinds) pendingKinds.add(kind);
+      queue.request();
+    }
+  });
+  log(`[Rust] Watching ${import_node_path.default.relative(process.cwd(), rustRoot) || "rust"}/ and ${import_node_path.default.relative(process.cwd(), target.specPath)}`);
+  log("[Rust] Waiting for changes...");
+  return { stop: () => watcher.close() };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   build,
@@ -384,5 +465,6 @@ function build(platform) {
   init,
   packageRoot,
   readJson,
-  run
+  run,
+  watch
 });

package/dist/react-native-rust.js

@@ -39,6 +39,7 @@ Usage:
   react-native-rust build ios        Build an iOS XCFramework
   react-native-rust build android    Build Android static archives for supported ABIs
   react-native-rust build web        Build a WebAssembly package for react-native-web
+  react-native-rust watch            Watch the Spec and rust/ for changes and rebuild automatically
   react-native-rust --help           Show this help
 
 Create a library first with the C++ module template from:
@@ -106,6 +107,19 @@ function main(args) {
     (0, import_app.runCodegen)(appRoot, appModule);
     return (0, import_app.inDirectory)(appModule, () => (0, import_react_native_rust_lib.build)(option));
   }
+  if (command === "watch") {
+    if (appModule) process.chdir(appModule);
+    const handle = (0, import_react_native_rust_lib.watch)(appModule ? { onGenerated: () => (0, import_app.runCodegen)(appRoot, appModule) } : {});
+    const shutdown = (signal) => {
+      console.log(`
+[Rust] Received ${signal}, stopping watcher...`);
+      handle.stop().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGHUP", () => shutdown("SIGHUP"));
+    return;
+  }
   throw new Error(`Unknown command: ${command}. Run react-native-rust --help for usage.`);
 }
 try {

package/metro.js

@@ -0,0 +1,2 @@
+// Entry point for `require('@rejaul/react-native-rust/metro')`.
+module.exports = require('./dist/metro.js');

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@rejaul/react-native-rust",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Generate Rust and native bindings from React Native TurboModule TypeScript interfaces.",
   "engines": {
     "node": ">=18"
   },
   "files": [
     "dist/",
+    "metro.js",
     "README.md",
     "LICENSE",
     "CONTRIBUTING.md",
@@ -47,6 +48,7 @@
   },
   "homepage": "https://github.com/DeveloperRejaul/react-native-rust#readme",
   "dependencies": {
+    "chokidar": "^3.6.0",
     "typescript": "^5.9.3"
   },
   "devDependencies": {