npm package: @qlik/react-native-helium
Description: Skia base JSI renderer for Picasso and Nebula
Author: Qlik
Latest version: 3.0.1

# @qlik/react-native-helium

<img src="logo/he2.png" height="256"/>

Skia-based JSI renderer for Picasso and Nebula — built on the **React Native New Architecture** (Fabric + TurboModules).

## Overview

`@qlik/react-native-helium` provides a high-performance 2D canvas rendering pipeline that bridges JavaScript to native GPU-accelerated graphics via [Skia](https://skia.org/). It is the rendering backbone for **Picasso.js** and **Nebula** chart visualizations in Qlik's mobile applications.

### Key Features

- **Fabric** native view rendering (`RCTViewComponentView` on iOS, codegen `ViewManagerDelegate` on Android)
- **C++ TurboModule** for zero-overhead JSI binding installation (no Bridge serialization)
- **Codegen** type-safe specs for both the TurboModule and the Fabric `CanvasView` component
- **Metal** rendering on iOS, **OpenGL ES 2.0** (EGL) on Android
- Spatial indexing via `QuadTree` for efficient tap/lasso selection
- Virtual canvas layers for compositing chart components

### Requirements

| | Minimum |
|---|---|
| **React Native** | 0.78.x |
| **React** | 19.x |
| **iOS** | 13.4 |
| **Android SDK** | 33 |
| **C++ (iOS)** | C++20 |
| **C++ (Android)** | C++17 |
| **NDK** | 27.1.12297006 |

### Peer Dependencies

- `@qlik/carbon-core` (^2.0.0)
- `react` (19.x)
- `react-native`

## Installation

```bash
npm install @qlik/react-native-helium
# or
yarn add @qlik/react-native-helium
```

### iOS

```bash
cd ios && pod install
```

The podspec uses `install_modules_dependencies(s)` to configure Fabric and TurboModule CocoaPods dependencies automatically.

### Android

No additional steps — the `com.facebook.react` Gradle plugin handles autolinking and codegen.

## Usage

```typescript
// 1. Initialize (once, at app startup)
import { installHelium, Canvas } from "@qlik/react-native-helium";
installHelium();

// 2. Use the Canvas component
<Canvas
  lasso={false}
  onCanvas={(canvasApi) => {
    canvasApi.addShapes([/* shape descriptors */]);
    canvasApi.draw();
  }}
  onResized={() => { /* handle resize */ }}
/>
```

`installHelium()` calls the C++ TurboModule via `TurboModuleRegistry.getEnforcing()`, which installs the `HeliumCanvasApi` global on the JSI runtime. The `Canvas` component uses the codegen Fabric native component (`codegenNativeComponent('CanvasView')`).

## Running the Example App

To build, develop and run, please see https://github.com/qlik-oss/react-native-carbon

The `Helium4/` directory contains an example app that renders a scrollable grid of Picasso.js charts.

---

# Build Guide: Harfbuzz, ICU & Skia

This document provides instructions for building **Harfbuzz**, **ICU** and **Skia** for **Android** and **iOS** platforms.  

---

## ⚙️ Prerequisites

Before building, ensure you have the following tools installed and correctly set up.  

### 🔹 Common Tools
| Tool | Required For | How to Check |
|------|--------------|--------------|
| **Git** | Clone repositories | `git --version` |
| **Python 3** | Meson build system | `python3 --version` |
| **Ninja** | Build system backend | `ninja --version` |
| **CMake (≥3.18)** | Android build | `cmake --version` |
| **Meson (≥0.60)** | iOS build | `meson --version` |
| **pkg-config** | Dependency discovery | `pkg-config --version` |

### 🔹 Android Specific
| Tool | Required For | How to Check |
|------|--------------|--------------|
| **Android Studio / SDK** | SDK + NDK setup | Open Android Studio > Preferences > SDK |
| **Android NDK (≥23.1)** | CMake builds | `ls $ANDROID_HOME/ndk/` |
| **Java (JDK ≥11)** | Gradle + build tools | `java -version` |

👉 Set environment variables in your shell config (`~/.zshrc` or `~/.bashrc`):
```bash
export ANDROID_HOME=$HOME/Library/Android/sdk
export ANDROID_NDK=$ANDROID_HOME/ndk/23.1.7779620
export PATH=$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$PATH
```

### 🔹 iOS Specific
| Tool | Required For | How to Check |
|------|--------------|--------------|
| **Xcode (≥14)** | iOS SDKs + compilers | `xcodebuild -version` |
| **Xcode Command Line Tools** | clang, ar, strip | `xcode-select -p` |
| **CocoaPods** *(optional)* | Dependency mgmt | `pod --version` |

👉 Make sure SDK paths exist:
```bash
ls /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/
ls /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/
```

If these return valid `.sdk` folders (e.g., `iPhoneOS18.2.sdk`), you’re good.  

---

## 📦 Harfbuzz

### 🔹 Android

- **Repository:** [harfbuzz/harfbuzz](https://github.com/harfbuzz/harfbuzz.git)  
- **Branch:** (Specify branch if needed)  

#### Steps

1. **Checkout the branch:**
   ```bash
   git clone https://github.com/harfbuzz/harfbuzz.git
   cd harfbuzz
   git checkout <branch>
   ```

2. **Create a bash script (e.g., `build_android.sh`):**

   ```bash
   #!/bin/bash
   set -o errexit -o nounset
   cd build/android

   cmake ../..      -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake      -DANDROID_ABI=arm64-v8a      -DANDROID_PLATFORM=android-31      -DCMAKE_BUILD_TYPE=Release      -DHB_HAVE_FREETYPE=OFF      -DHB_BUILD_SHARED=OFF      -GNinja

   ninja install
   ```

3. **Run the script:**
   ```bash
   bash build_android.sh
   ```

⚠️ **Note:** Building Harfbuzz for Android using **Meson** currently has known issues. Prefer **CMake**.

---

### 🔹 iOS

- **Repository:** [harfbuzz/harfbuzz](https://github.com/harfbuzz/harfbuzz.git)  
- **Branch:** (Specify branch if needed)  

#### Steps

1. **Checkout the branch:**
   ```bash
   git clone https://github.com/harfbuzz/harfbuzz.git
   cd harfbuzz
   git checkout <branch>
   ```

2. **Create cross files** for Simulator and Device builds.  

   - **Simulator Example (`ios_cross_sim.txt`)**  
     *(see earlier section for full contents)*

   - **Device Example (`ios_cross_dev.txt`)**  
     *(same structure, but with `iPhoneOS.platform` SDK)*

3. **Run Meson setup:**
   ```bash
   meson setup --cross-file ios_cross_dev.txt ios_dev_arm64 -Ddefault_library=static -Dtests="disabled"
   ```

4. **Build with Ninja:**
   ```bash
   ninja -C ios_dev_arm64
   ```

---

## 📦 ICU

### 🔹 Android

- **Repository:** [unicode-org/icu](https://github.com/unicode-org/icu.git)  
- **Branch:** `release-70-rc`  

#### Steps

1. **Clone the repo & checkout branch:**
   ```bash
   git clone https://github.com/unicode-org/icu.git
   cd icu
   git checkout release-70-rc
   ```

2. **Create directories:**
   ```
   icu/icu4c/android
   icu/icu4c/macOS
   ```

3. **Copy build script (`build_icu_android.sh`) into `icu/icu4c/android`.**

4. **Run the script:**
   ```bash
   cd icu/icu4c/android
   bash build_icu_android.sh
   ```

---

### 🔹 iOS

- **Repository:** [dbquarrel/icu4c-xcframework](https://github.com/dbquarrel/icu4c-xcframework)  

#### Steps

1. **Checkout the repo:**
   ```bash
   git clone https://github.com/dbquarrel/icu4c-xcframework.git
   cd icu4c-xcframework
   git checkout <branch>
   ```

---

✅ With this, you’ll be able to build **Harfbuzz** and **ICU** for **Android** and **iOS** successfully.  


---

## 📦 Skia

### 🔹 Android

- **Repositories:**
  1. [chromium.googlesource.com Skia](https://chromium.googlesource.com/experimental/external/gob/skia/skia/)  
  2. [google/skia (GitHub)](https://github.com/google/skia/tree/main)  

- **Branch:** *Yet to find (update once finalized)*  

#### Steps

1. **Clone the repository and checkout branch:**
   ```bash
   git clone https://github.com/google/skia.git
   cd skia
   git checkout <branch>
   ```

2. **Sync dependencies:**
   ```bash
   python tools/git-sync-deps
   ```

3. **Copy `android_lib.sh` script** to the **root directory** of the repository.  

4. **Run the script:**
   ```bash
   bash android_lib.sh
   ```

---

### 🔹 iOS

- **Repositories:**
  1. [chromium.googlesource.com Skia](https://chromium.googlesource.com/experimental/external/gob/skia/skia/)  
  2. [google/skia (GitHub)](https://github.com/google/skia/tree/main)  

- **Branch:** *Yet to find (update once finalized)*  

#### Steps

1. **Clone the repository and checkout branch:**
   ```bash
   git clone https://github.com/google/skia.git
   cd skia
   git checkout <branch>
   ```

2. **Sync dependencies:**
   ```bash
   python tools/git-sync-deps
   ```

3. **Copy `create-framework.sh` script** to the **root directory** of the repository.  

4. **Run the script:**
   ```bash
   bash create-framework.sh
   ```

---

## ⚠️ Notes

- Ensure the script paths in `android_lib.sh` and `create-framework.sh` are updated correctly before execution.  
- The build process may require additional tools such as **Python 3, Ninja, CMake, Xcode (for iOS), Android NDK (for Android)**.  
- Some dependencies may take time to download when running `git-sync-deps`.  

---

Note: where ios/headers has a copy of the skia/include folder

✅ With this guide, you can build **Skia** for **Android** and **iOS**.  


## License

MIT