@cloud2303/react-native-singbox

A native sing-box runtime SDK for React Native and Expo, powered by Nitro Modules.

Installation

npm install @cloud2303/react-native-singbox react-native-nitro-modules

Expo projects must add the config plugin and set an iOS bundle identifier:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.example.app"
    },
    "plugins": ["@cloud2303/react-native-singbox/app.plugin"]
  }
}

Run npx expo prebuild after changing the plugin configuration. This package contains native code and therefore does not work in Expo Go.

API contract

• start(options) and stop() are asynchronous operations. They resolve only after the native runtime reaches a terminal state or times out.
• Operational failures are returned as CoreOperationResult. A rejected Promise is reserved for bridge/programming failures.
• getState() returns the current snapshot. addStateListener() provides subsequent transitions; remove only the listener ID returned by that call.
• getCapabilities() must be checked before showing platform-specific UI.
• Traffic values are bytes. uplink/downlink are current rates and uplinkTotal/downlinkTotal are totals for the running session.

const capabilities = core.getCapabilities()
if (!capabilities.vpn) {
  // This build cannot create a system VPN.
}

const listenerId = core.addStateListener((state) => {
  console.log(state.status, state.errorCode, state.errorMessage)
})

const result = await core.start({
  config,
  systemProxyEnabled: false,
  allowBypass: false,
  showRealtimeTraffic: true,
})

core.removeStateListener(listenerId)

An empty errorCode and errorMessage mean that the current state has no operational error. Notification permission is optional: when capabilities.notificationPermission is false, hasNotificationPermission() returns true because no runtime permission is required.

Platform capabilities

Android currently supports VPN, traffic statistics, installed-app discovery, per-app routing, and Android 10+ system HTTP proxy configuration. Notification permission is requested only on Android 13+ and never blocks VPN startup.

For Android route debugging, sing-box logs enabled by the configuration's log.level are forwarded to the SingboxRoute Logcat tag:

adb logcat -v time -s SingboxRoute

The iOS Packet Tunnel extension forwards the same configured logs to unified logging with the SingboxRoute category. On a connected device, select the Packet Tunnel process in Xcode's console and filter for SingboxRoute.

iOS uses the same process split as the official sing-box Apple client:

• The React Native host owns NETunnelProviderManager only.
• The Expo config plugin creates and embeds a PacketTunnel app-extension target during prebuild.
• libbox, its command server, TUN network settings, default-network monitor, sleep/wake handling, and traffic sampler all run inside that extension.
• Start/reload options are encoded as a binary property list and persisted in the variant-specific App Group (group.<host bundle identifier>).

The plugin also declares the Packet Tunnel target through extra.eas.build.experimental.ios.appExtensions, so EAS can provision the extension separately. A physical-device build still needs an Apple team whose host app and extension profiles include Network Extension and App Groups.

Native core binaries

The npm package contains android/libs/libbox.aar and ios/Libbox.xcframework. They are built from the same sing-box revision and are intentionally ignored by Git.

See BUILD_LIBBOX.md for the build tags and commands.

Package development

The public TypeScript contract is maintained in the private development sources. Run npm run specs after changing it and commit the regenerated Nitrogen native bindings.

npm pack and npm publish run a clean TypeScript build and a package-content check. Only compiled JavaScript, declarations, required native sources, generated bindings, and native binaries are published. The top-level TypeScript src/ directory, source maps, build cache, and development config are excluded.

Licensing

The React Native wrapper is MIT licensed. The bundled sing-box binaries remain subject to sing-box's GPL-3.0-or-later terms; see THIRD_PARTY_NOTICES.md.