@dynlabs/react-native-image-to-webp 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# @dynlabs/react-native-image-to-webp
+
+A production-ready React Native library for converting images to WebP format with presets, resizing, and high-performance native implementations.
+
+## Features
+
+- 🚀 **TurboModule** (New Architecture only) for optimal performance
+- 🎨 **5 Presets**: balanced, small, fast, lossless, document
+- 📐 **Smart Resizing**: Preserve aspect ratio with `maxLongEdge`
+- 🔒 **Privacy-First**: Strips EXIF metadata by default
+- ⚡ **High Performance**: Native decoders + libwebp encoding, all off main thread
+- 📱 **iOS & Android**: Platform-optimized implementations
+- 🛡️ **Type-Safe**: Full TypeScript support with strict types
+
+## Requirements
+
+- React Native >= 0.68
+- **New Architecture (TurboModules) enabled**
+- iOS 11.0+ / Android API 24+
+
+## Installation
+
+```bash
+npm install @dynlabs/react-native-image-to-webp
+# or
+yarn add @dynlabs/react-native-image-to-webp
+```
+
+### iOS
+
+```bash
+cd ios && pod install && cd ..
+```
+
+### Android
+
+No additional setup required. The library uses CMake for native builds.
+
+## Quick Start
+
+```typescript
+import { convertImageToWebP } from '@dynlabs/react-native-image-to-webp';
+
+const result = await convertImageToWebP({
+  inputPath: '/path/to/image.jpg',
+  preset: 'balanced',
+  maxLongEdge: 2048,
+});
+
+console.log(`Output: ${result.outputPath}`);
+console.log(`Size: ${result.sizeBytes} bytes`);
+console.log(`Dimensions: ${result.width}×${result.height}`);
+```
+
+## API
+
+### `convertImageToWebP(options: ConvertOptions): Promise<ConvertResult>`
+
+#### Options
+
+| Parameter       | Type            | Required | Default        | Description                               |
+| --------------- | --------------- | -------- | -------------- | ----------------------------------------- |
+| `inputPath`     | `string`        | ✅       | -              | Path to input image file                  |
+| `outputPath`    | `string`        | ❌       | Auto-derived   | Output WebP file path                     |
+| `preset`        | `ConvertPreset` | ❌       | `'balanced'`   | Preset configuration                      |
+| `maxLongEdge`   | `number`        | ❌       | -              | Max dimension (preserves aspect ratio)    |
+| `quality`       | `number`        | ❌       | Preset default | Quality 0-100 (overrides preset)          |
+| `method`        | `number`        | ❌       | Preset default | Compression method 0-6 (overrides preset) |
+| `lossless`      | `boolean`       | ❌       | Preset default | Use lossless encoding (overrides preset)  |
+| `stripMetadata` | `boolean`       | ❌       | `true`         | Strip EXIF metadata                       |
+
+#### Result
+
+```typescript
+{
+  outputPath: string; // Path to created WebP file
+  width: number; // Image width in pixels
+  height: number; // Image height in pixels
+  sizeBytes: number; // Output file size in bytes
+}
+```
+
+## Presets
+
+| Preset     | Quality | Method | Use Case                                                |
+| ---------- | ------- | ------ | ------------------------------------------------------- |
+| `balanced` | 80      | 3      | **Default**. General-purpose, good quality/size balance |
+| `small`    | 74      | 5      | Optimized for smaller file sizes                        |
+| `fast`     | 78      | 1      | Faster encoding, slightly larger files                  |
+| `lossless` | -       | 4      | Perfect quality, larger files                           |
+| `document` | 82      | 4      | Documents, images with text/transparency                |
+
+### Examples
+
+```typescript
+// Balanced (default)
+await convertImageToWebP({
+  inputPath: '/path/to/image.jpg',
+  preset: 'balanced',
+});
+
+// Small file size
+await convertImageToWebP({
+  inputPath: '/path/to/image.jpg',
+  preset: 'small',
+  maxLongEdge: 1024,
+});
+
+// Lossless
+await convertImageToWebP({
+  inputPath: '/path/to/image.jpg',
+  preset: 'lossless',
+});
+
+// Custom quality
+await convertImageToWebP({
+  inputPath: '/path/to/image.jpg',
+  quality: 90,
+  method: 4,
+  maxLongEdge: 2048,
+});
+```
+
+## Resizing
+
+Use `maxLongEdge` to resize images while preserving aspect ratio:
+
+```typescript
+// Resize so longest edge is max 2048px
+await convertImageToWebP({
+  inputPath: '/path/to/large-image.jpg',
+  maxLongEdge: 2048, // If image is 4000×3000, becomes 2048×1536
+});
+```
+
+**Recommendation**: Always use `maxLongEdge` for better performance and smaller files. Common values:
+
+- **Thumbnails**: 512
+- **Mobile display**: 1024
+- **Retina display**: 2048 (recommended default)
+- **High-res**: 3072
+
+## Error Handling
+
+```typescript
+import {
+  convertImageToWebP,
+  ImageToWebPError,
+  ERROR_CODES,
+} from '@dynlabs/react-native-image-to-webp';
+
+try {
+  const result = await convertImageToWebP({ inputPath: '/path/to/image.jpg' });
+} catch (error) {
+  if (error instanceof ImageToWebPError) {
+    switch (error.code) {
+      case ERROR_CODES.FILE_NOT_FOUND:
+        console.error('File not found');
+        break;
+      case ERROR_CODES.DECODE_FAILED:
+        console.error('Failed to decode image');
+        break;
+      case ERROR_CODES.ENCODE_FAILED:
+        console.error('Failed to encode WebP');
+        break;
+      // ... other error codes
+    }
+  }
+}
+```
+
+### Error Codes
+
+- `INVALID_INPUT`: Invalid parameters
+- `FILE_NOT_FOUND`: Input file doesn't exist
+- `DECODE_FAILED`: Failed to decode input image
+- `ENCODE_FAILED`: Failed to encode WebP
+- `IO_ERROR`: File I/O error
+- `UNSUPPORTED_FORMAT`: Unsupported image format
+
+## Supported Formats
+
+### iOS
+
+- JPEG, PNG, HEIC/HEIF, TIFF, GIF (first frame), WebP
+
+### Android
+
+- JPEG, PNG, WebP, HEIF (API 28+), GIF (first frame)
+
+## Performance
+
+- All processing runs **off the main thread** (background queue/executor)
+- Uses platform-native decoders (ImageIO on iOS, ImageDecoder/BitmapFactory on Android)
+- Resize before encoding for best performance
+- Typical encoding time: 0.5-2s for 2000×1500 images (varies by device/preset)
+
+See [PERFORMANCE.md](docs/PERFORMANCE.md) for detailed performance guidance.
+
+## Architecture
+
+This library uses React Native's **New Architecture (TurboModules)**:
+
+- Type-safe Codegen interfaces
+- Native implementations for iOS (ObjC++) and Android (Kotlin + JNI)
+- Shared C++ code using libwebp for encoding
+- Background threading for non-blocking operations
+
+See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.
+
+## Documentation
+
+- [API Reference](docs/API.md) - Complete API documentation
+- [Architecture](docs/ARCHITECTURE.md) - Technical architecture details
+- [Performance Guide](docs/PERFORMANCE.md) - Performance optimization tips
+- [Contributing](docs/CONTRIBUTING.md) - Development setup and guidelines
+- [Release Process](docs/RELEASE.md) - Versioning and release workflow
+- [Security](docs/SECURITY.md) - Security policy and considerations
+
+## Example App
+
+See the [example app](example/) for a complete usage example.
+
+```bash
+# Run example on iOS
+yarn example:ios
+
+# Run example on Android
+yarn example:android
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT
+
+## Related
+
+- [libwebp](https://github.com/webmproject/libwebp) - WebP encoding library
+- [React Native New Architecture](https://reactnative.dev/docs/the-new-architecture/landing-page) - TurboModules documentation
+
+---
+
+Made with ❤️ for the React Native community

package/ReactNativeImageToWebp.podspec

@@ -0,0 +1,35 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativeImageToWebp"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => ".git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}", "cpp/**/*.{h,cpp}"
+  s.private_header_files = "ios/**/*.h", "cpp/**/*.h"
+
+  # Include libwebp sources if vendored
+  libwebp_path = File.join(__dir__, "cpp/vendor/libwebp/src")
+  if Dir.exist?(libwebp_path)
+    s.source_files += "cpp/vendor/libwebp/src/**/*.{c,h}"
+    s.public_header_files = "cpp/vendor/libwebp/src/webp/*.h"
+    s.compiler_flags = "-O3 -DNDEBUG -DWEBP_AVAILABLE"
+  else
+    Pod::UI.warn "libwebp not found at #{libwebp_path}. Please vendor libwebp sources."
+    s.compiler_flags = "-O3 -DNDEBUG"
+  end
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "$(inherited) ${PODS_ROOT}/Headers/Private/React-Core",
+    "OTHER_CPLUSPLUSFLAGS" => "$(OTHER_CFLAGS) -std=c++17"
+  }
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,85 @@
+buildscript {
+  ext.ReactNativeImageToWebp = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return ReactNativeImageToWebp[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.dynlabs.reactnativeimagetowebp"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-std=c++17", "-O3", "-DNDEBUG"
+        arguments "-DANDROID_STL=c++_shared"
+      }
+    }
+
+    ndk {
+      abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "src/main/cpp/CMakeLists.txt"
+      version "3.22.1"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,67 @@
+cmake_minimum_required(VERSION 3.22.1)
+
+project("react-native-image-to-webp")
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Release flags
+set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3 -DNDEBUG")
+set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS_RELEASE} -O3 -DNDEBUG")
+
+# Include directories
+include_directories(
+  ${CMAKE_CURRENT_SOURCE_DIR}/../../../cpp
+)
+
+# Check if libwebp is vendored
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/../../../cpp/vendor/libwebp/src")
+  # libwebp is vendored, include it
+  include_directories(
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../../cpp/vendor/libwebp/src
+  )
+  
+  # Add libwebp source files
+  file(GLOB_RECURSE WEBP_SOURCES
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../cpp/vendor/libwebp/src/enc/*.c"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../cpp/vendor/libwebp/src/dec/*.c"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../cpp/vendor/libwebp/src/dsp/*.c"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../cpp/vendor/libwebp/src/utils/*.c"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../cpp/vendor/libwebp/src/webp/*.c"
+  )
+  
+  # Define WEBP_AVAILABLE preprocessor macro
+  add_definitions(-DWEBP_AVAILABLE)
+  
+  message(STATUS "libwebp found, including sources")
+else()
+  message(WARNING "libwebp not found. Please vendor libwebp to cpp/vendor/libwebp/")
+  set(WEBP_SOURCES "")
+endif()
+
+# Source files
+set(SOURCES
+  ImageToWebPJNI.cpp
+  ../../../cpp/ImageToWebP.cpp
+  ${WEBP_SOURCES}
+)
+
+# Create shared library
+add_library(
+  react-native-image-to-webp
+  SHARED
+  ${SOURCES}
+)
+
+# Link libraries
+find_library(
+  log-lib
+  log
+)
+
+target_link_libraries(
+  react-native-image-to-webp
+  ${log-lib}
+  # libwebp static library would be linked here if built separately
+)

package/android/src/main/cpp/ImageToWebPJNI.cpp

@@ -0,0 +1,73 @@
+#include <jni.h>
+#include <string>
+#include <fstream>
+#include "ImageToWebP.h"
+
+extern "C" {
+
+JNIEXPORT jboolean JNICALL
+Java_com_dynlabs_reactnativeimagetowebp_ReactNativeImageToWebpModule_nativeEncodeWebP(
+    JNIEnv *env,
+    jobject /* this */,
+    jbyteArray rgbaData,
+    jint width,
+    jint height,
+    jint quality,
+    jint method,
+    jboolean lossless,
+    jstring outputPath) {
+
+  // Get RGBA data
+  jbyte *data = env->GetByteArrayElements(rgbaData, NULL);
+  if (!data) {
+    return JNI_FALSE;
+  }
+
+  jsize dataLength = env->GetArrayLength(rgbaData);
+  if (dataLength != width * height * 4) {
+    env->ReleaseByteArrayElements(rgbaData, data, JNI_ABORT);
+    return JNI_FALSE;
+  }
+
+  // Convert output path
+  const char *pathStr = env->GetStringUTFChars(outputPath, NULL);
+  if (!pathStr) {
+    env->ReleaseByteArrayElements(rgbaData, data, JNI_ABORT);
+    return JNI_FALSE;
+  }
+
+  std::string outputPathStr(pathStr);
+
+  // Prepare encoding options
+  WebPEncodeOptions options;
+  options.quality = quality;
+  options.method = method;
+  options.lossless = (lossless == JNI_TRUE);
+  options.stripMetadata = true;
+  options.threadLevel = 1;
+
+  // Encode
+  const uint8_t *rgba = reinterpret_cast<const uint8_t *>(data);
+  WebPEncodeResult result = encodeWebP(
+      rgba,
+      static_cast<uint32_t>(width),
+      static_cast<uint32_t>(height),
+      options,
+      outputPathStr);
+
+  // Cleanup
+  env->ReleaseStringUTFChars(outputPath, pathStr);
+  env->ReleaseByteArrayElements(rgbaData, data, JNI_ABORT);
+
+  return result.success ? JNI_TRUE : JNI_FALSE;
+}
+
+JNIEXPORT jstring JNICALL
+Java_com_dynlabs_reactnativeimagetowebp_ReactNativeImageToWebpModule_nativeGetLastError(
+    JNIEnv *env,
+    jobject /* this */) {
+  // TODO: Store last error in thread-local storage
+  return env->NewStringUTF("Encoding failed");
+}
+
+} // extern "C"