DOCSEARCHbyAlgolia
Submit Docs

Craby

repository·main·Indexed 42 days ago

https://github.com/leegeunhyeok/craby

A tool for writing type-safe Rust code in React Native applications. Craby automates the creation of bindings between TypeScript and Rust by leveraging pure C++ TurboModules, bypassing platform-specific layers like ObjCTurboModule and JavaTurboModule. It requires React Native 0.76+ with the New Architecture enabled, Node.js 18+, and Rust 1.90+.

Tokens
37.1K
Snippets
128
Records
192
Agent score
51%

What's inside Craby

  1. What is Craby?

    main
    Craby is a type-safe development tool for React Native that enables high-performance native modules written in Rust. It works by automatically generating Rust and C++ bindings from TypeScript schemas and integrating directly with pure C++ TurboModule. By bypassing platform-specific compatibility layers like ObjCTurboModule (iOS) and JavaTurboModule (Android), Craby achieves near-zero overhead for cross-language communication.

  2. Overview of Craby

    main
    Craby is a development tool designed to provide type-safe Rust integration for React Native applications. It automates the generation of Rust/C++ bindings based on TypeScript schemas. A key architectural feature is its direct integration with pure C++ TurboModule, which allows it to bypass platform-specific layers such as ObjCTurboModule (iOS) and JavaTurboModule (Android), streamlining the bridge between Rust and the React Native runtime.

  6. Identify the @craby/cli-bindings-linux-x64-musl package

    main
    The @craby/cli-bindings-linux-x64-musl package provides the pre-compiled x86_64-unknown-linux-musl binary for the @craby/cli-bindings library. Use this specific package if your target environment is a Linux system using the musl C library (common in Alpine Linux or other lightweight container environments) on an x86_64 architecture.

  7. Understand Craby's platform and TurboModule limitations

    main

    Craby is optimized for performance-critical pure computation modules. It is not intended for modules that require direct access to native platform capabilities or standard React Native TurboModule features.

    Unsupported Platform-Specific Features

    Craby does not support APIs requiring direct native access, including:

    • Camera, microphone, and sensor access
    • Native UI components and view managers
    • Platform-specific services (e.g., location services, notifications, background tasks)
    • Direct integration with platform SDKs (e.g., ARKit, MLKit, Firebase native modules)

    Note: App data I/O (File I/O) operations are fully supported.

    Unsupported TurboModule Features

    Craby does not support the following standard TurboModule capabilities:

    • Event emitters (NativeEventEmitter)
    • Platform context access (e.g., Context on Android, UIApplication on iOS)
    • Native module lifecycle callbacks
    • Direct access to React Native bridge APIs

  9. How error handling works in Craby

    main

    Craby modules use two distinct strategies for error handling depending on whether the operation is synchronous or asynchronous:

    1. Panics: Used for synchronous, immediate errors. When you use the throw! macro in Rust, the panic is caught by std::panic::catch_unwind(), converted into a C++ exception, and finally emitted as a jsi::JSError in the JavaScript runtime. This allows synchronous Rust errors to be caught using standard JavaScript try/catch blocks.

    2. Promise Rejections: Used for recoverable errors in asynchronous operations. Instead of throwing an exception, you return a rejected promise. These are handled in JavaScript using await within a try/catch block or by attaching a .catch() handler to the returned Promise.

  10. Type Mapping Overview between TypeScript, Rust, and C++

    main

    Craby automatically converts types between TypeScript, Rust, and C++ at compile-time using zero-cost abstractions. This allows you to define interfaces in TypeScript and implement them in Rust or C++ seamlessly.

    Core Type Mapping

    TypeScriptRustC++
    booleanboolbool
    numberf64double
    string&str (params) / String (others)std::string
    objectstructstruct
    ArrayBufferVec<u8>std::vector<uint8_t>
    T[]Vec<T>std::vector<T>
    T | nullNullable<T>struct
    Promise<T>Result<T>T (Unwrapped)
    enumenumenum class
    void()void

    Rust Type Aliases

    Craby provides aliases in Rust to make types more familiar to TypeScript developers:

    • bool $\rightarrow$ Boolean
    • f64 $\rightarrow$ Number
    • Vec<u8> $\rightarrow$ ArrayBuffer
    • Vec<T> $\rightarrow$ Array<T>
    • Result<T> $\rightarrow$ Promise<T>
    • () $\rightarrow$ Void

  11. What are Signals in Craby?

    main

    Signals are a mechanism for one-way, asynchronous communication from native Rust code to JavaScript. They allow your native module to emit events that trigger callbacks within your React Native application.

    Key Characteristics:

    • Directional: Flows only from Rust $\rightarrow$ JavaScript.
    • Payloads: Can optionally carry data payloads to the JavaScript side.
    • Non-blocking: Signals are emitted asynchronously and do not block the native execution thread.
    • Multi-listener support: JavaScript can register multiple independent listeners for the same signal.

  12. Understanding Synchronous vs Asynchronous methods in Craby

    main

    Craby provides two execution models for native methods, allowing you to balance performance and UI responsiveness:

    1. Synchronous (Sync): Methods execute immediately on the JavaScript thread. They return values directly (e.g., number, string). Because they run on the JS thread, they block execution until they complete. Use these for lightweight operations that finish in under 16ms (to maintain 60fps).

    2. Asynchronous (Async): Methods return a Promise<T> and execute in separate threads managed by the C++ layer. This prevents the UI from freezing during heavy computations. Use these for any operation that takes longer than 16ms or involves heavy CPU work.

    AspectSyncAsync (Promise)
    ExecutionJS threadSeparate thread
    ReturnsTPromise<T>
    Duration< 16msAny duration
    Heavy WorkAvoidPerfect for
    UI ImpactBlockingNon-blocking
    Use CasesMath, formattingHeavy compute, complex algorithms