{"id":35252832,"url":"https://github.com/vpnclient/vpnclient-engine-react-native","last_synced_at":"2026-04-06T06:32:01.334Z","repository":{"id":286760654,"uuid":"941801473","full_name":"VPNclient/VPNclient-engine-react-native","owner":"VPNclient","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-05T19:43:40.000Z","size":31,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-02T13:52:43.982Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VPNclient.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-03T04:28:04.000Z","updated_at":"2025-05-16T01:55:09.000Z","dependencies_parsed_at":"2025-12-30T14:10:02.073Z","dependency_job_id":null,"html_url":"https://github.com/VPNclient/VPNclient-engine-react-native","commit_stats":null,"previous_names":["vpnclient/vpnclient-engine-react-native"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VPNclient/VPNclient-engine-react-native","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VPNclient%2FVPNclient-engine-react-native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VPNclient%2FVPNclient-engine-react-native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VPNclient%2FVPNclient-engine-react-native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VPNclient%2FVPNclient-engine-react-native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VPNclient","download_url":"https://codeload.github.com/VPNclient/VPNclient-engine-react-native/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VPNclient%2FVPNclient-engine-react-native/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31463012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-30T07:02:20.617Z","updated_at":"2026-04-06T06:32:01.310Z","avatar_url":"https://github.com/VPNclient.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# VPN Client Engine React Native (React Native Module)\n\nHere's a proposed English version of a modified `README.md` for [VPNclient-engine-react-native](https://github.com/VPNclient/VPNclient-engine-react-native), making it clear that Flutter is the main development focus and inviting React Native contributors:\n\n---\n\n## ⚠️ Project Status: Flutter-first\n\nThis repository provides a React Native wrapper for [VPNclient Engine](https://github.com/VPNclient/VPNclient-engine).\n**However, the main active development is happening in the [Flutter plugin repository](https://github.com/VPNclient/VPNclient-engine-flutter).**\n\n---\n\n## 🤝 Contributing (Call for Contributors)\n\nWe are looking for developers interested in maintaining and improving this React Native integration.\nIf you're passionate about networking, VPN technology, or bridging native code with React Native — we’d love your help!\nFeel free to open an issue, start a discussion, or submit a pull request.\n\n---\n\n## 🔗 Related Projects\n\n* Core Engine: [VPNclient-engine](https://github.com/VPNclient/VPNclient-engine)\n* Flutter Plugin: [VPNclient-engine-flutter](https://github.com/VPNclient/VPNclient-engine-flutter)\n* Example App: [VPNclient-app](https://github.com/VPNclient/VPNclient-app)\n  \n**VPN Client Engine React Native** is a React Native module that provides a high-level API for controlling VPN connections from a React Native app. It wraps the native [VPNclient Engine](https://github.com/VPNclient/VPNclient-engine) library, allowing React Native developers to integrate advanced VPN functionality into their apps with ease. With this module, you can start and stop VPN connections, switch servers, apply routing rules, and listen to connection events using simple JavaScript calls, without worrying about platform-specific implementation details.\n\n## 🚀 Key Features\n- **Seamless Integration:** The module is built to be cross-platform. It uses platform-specific binaries and code (written in C++ and integrated via native modules) to interface with iOS, Android, Windows, macOS, and Linux, but exposes a unified JavaScript interface. This means you write your VPN logic once in JavaScript and it works everywhere React Native does.\n- **Intuitive API:** The API is designed with React Native developers in mind. You can initialize the VPN engine, connect to a server, and listen for status changes using promises and event listeners. The module handles asynchronous calls and background threads internally.\n- **Powered by VPNclient Engine:** Under the hood, this module utilizes the native VPNclient Engine, which supports multiple protocols (Xray/VMess/VLESS/Reality, WireGuard, OpenVPN, etc.) and drivers. The module abstracts the complexity, so you can, for example, simply call `connect()` and the engine will take care of setting up a tun interface or proxy as needed on that platform.\n\n## 🖥️ Supported Platforms\n\n- ✅ iOS (15.0+)\n- ✅ Android (5.0+) \n- ✅ macOS (Intel/Silicon)\n- ✅ Windows  \n- ✅ Unix (Linux/Debian/Ubuntu)\n\nEach platform uses the native capabilities provided by VPNclient Engine:\n- On Android and iOS, the engine uses the system VPN APIs (VpnService, NetworkExtension) to create a VPN tunnel.\n- On desktop, it can either create a TUN interface or run as a local proxy (depending on driver configuration).\n\n## 📦 Architecture\n\nInternally, the module acts as a bridge between JavaScript and the native engine. It uses a combination of native modules and platform-specific setup to communicate with the native library. The basic flow:\n\n```mermaid\nflowchart LR\n subgraph subGraph0[\"React Native Application\"]\n        UI@{ label: \"Your React Native App (\u003cspan style=\\\"color:\\\"\u003eJavaScript)\u003c/span\u003e\" }\n  end\n subgraph subGraph1[\"React Native Module\"]\n        Module[\"VPNclient Engine React Native\"]\n  end\n subgraph subGraph2[\"Native Core\"]\n        Core[\"VPNclient Engine Library\"]\n  end\n    UI --\u003e Module\n    Module --\u003e Core\n    Core --\u003e iOS[\"iOS\"] \u0026 Android[\"Android\"] \u0026 macOS[\"macOS\"] \u0026 Windows[\"Windows\"] \u0026 Linux[\"Linux\"]\n\n    UI@{ shape: rect}\n```\n\n*Diagram: Your React Native app calls into the VPNclient Engine React Native module (JavaScript layer). The module calls the native VPNclient Engine, which interfaces with the OS networking on each platform.* \n\nFrom a developer perspective, you primarily interact with the **JavaScript API** provided by this module. The module takes care of invoking native methods and ensures asynchronous operations (like connecting or disconnecting) do not block the UI thread.\n\n## Platform Setup\n\nBecause this module sets up actual VPN tunnels, a few platform-specific configurations are required:\n\n- **Android:** No special code is needed (the module internally uses Android's `VpnService`), but you must declare the following in your app’s AndroidManifest.xml:\n  ```xml\n  \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n  \u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE\" /\u003e\n  ```\n  These ensure the app can open network connections and run a foreground service for the VPN. The module will handle launching the VPN service. (Note: You do **not** need to declare `BIND_VPN_SERVICE` in the manifest; the module uses the VpnService class which has that intent filter built-in.)\n  \n- **iOS:** Enable the Personal VPN capability for your app target in Xcode (this adds the necessary entitlements). Additionally, in your Info.plist, you might need to include a usage description for VPN if required. The VPNclient Engine uses a custom bundle identifier for its network extension (`click.vpnclient.engine` with an `allow-vpn` key), but if you integrate via this module, typically enabling the capability is sufficient. When you run the app the first time, iOS will prompt the user to allow the VPN configuration.\n  \n- **Windows:** The app should be run with administrator privileges to create a TUN interface via WinTun. Alternatively, have the WinTun driver installed (which is usually present if WireGuard is installed on the system). No manifest changes are needed, but the user might need to approve driver installation if not already present.\n  \n- **macOS/Linux:** The application will likely require root privileges or proper entitlements to create a tunnel (on macOS, Network Extension needs to be signed with the correct entitlements; on Linux, either run with root or configure `/dev/net/tun` access for the user). For development on macOS, you can enable \"Network Extensions\" in the sandbox if running unsigned.\n\nOnce the above are set up, you can use the module in your JavaScript code as shown below.\n\n## 📥 Getting Started\n\nTo start using VPN Client Engine React Native, ensure you have React Native installed and set up your project accordingly.\n\n### 📦 Installation\n```sh\nnpm install vpnclient-engine-react-native\n# or\nyarn add vpnclient-engine-react-native\n```\n\nThen link the native dependencies:\n```sh\nnpx pod-install\n```\n\n## 📌 Example Usage\n\n```javascript\nimport VPNClientEngine from 'vpnclient-engine-react-native';\n\n// Initialize the Engine\nVPNClientEngine.initialize();\n\n// Clear subscriptions\nVPNClientEngine.clearSubscriptions();\n\n// Add subscription\nVPNClientEngine.addSubscription(\"https://pastebin.com/raw/ZCYiJ98W\");\n//VPNClientEngine.addSubscriptions([\"https://pastebin.com/raw/ZCYiJ98W\"]);\n\n// Update subscription\nawait VPNClientEngine.updateSubscription(0);\n\n// Listen for connection status changes\nVPNClientEngine.addListener('onConnectionStatusChanged', (status) =\u003e {\n  console.log(\"Connection status:\", status);\n});\n\n// Connect to server 1\nawait VPNClientEngine.connect(0, 1);\n\n// Set routing rules\nVPNClientEngine.setRoutingRules([\n  { appName: \"YouTube\", action: \"proxy\" },\n  { appName: \"google.com\", action: \"direct\" },\n  { domain: \"ads.com\", action: \"block\" },\n]);\n\n// Ping a server\nVPNClientEngine.ping(0, 1);\nVPNClientEngine.addListener('onPingResult', (result) =\u003e {\n  console.log(`Ping: sub=${result.subscriptionIndex}, server=${result.serverIndex}, latency=${result.latencyInMs} ms`);\n});\n\nsetTimeout(async () =\u003e {\n  // Disconnect\n  await VPNClientEngine.disconnect();\n}, 10000);\n```\n\n---\n\n## ⚙️ API Methods\n\n### 🔹 1. initialize()\nInitializes the VPN Client Engine. This should be called before using any other method.\n\n### 🔹 2. connect(subscriptionIndex: number, serverIndex: number)\nConnects to the specified VPN server.\n- `subscriptionIndex`: Index of the subscription.\n- `serverIndex`: Index of the server from the subscription.\n\n### 🔹 3. disconnect()\nDisconnects the active VPN connection.\n\n### 🔹 4. getConnectionStatus()\nReturns the current connection status (`connected`, `disconnected`, `connecting`, `error`).\n\n### 🔹 5. getServerList(subscriptionIndex: number)\nFetches the list of available VPN servers for a subscription.\n\n### 🔹 6. pingServer(subscriptionIndex: number, serverIndex: number)\nPings a specific server to check latency.\n- Returns: Promise with latency in milliseconds.\n\n### 🔹 7. setRoutingRules(rules: RoutingRule[])\nConfigures routing rules for apps or domains.\n- `rules`: Array of routing rules (e.g., route YouTube traffic through VPN, block ads.com).\n\n### 🔹 8. addSubscription(url: string)\nAdds a VPN subscription from the provided URL.\n\n### 🔹 9. addSubscriptions(urls: string[])\nAdds multiple VPN subscriptions from the provided URLs.\n\n### 🔹 10. updateSubscription(subscriptionIndex: number)\nUpdates the subscription at the given index.\n\n### 🔹 11. clearSubscriptions()\nClears all subscriptions.\n\n### 🔹 12. getSessionStatistics()\nReturns statistics for the current VPN session (e.g., data usage, session duration).\n\n### 🔹 13. setAutoConnect(enable: boolean)\nEnables or disables auto-connect functionality.\n\n### 🔹 14. setKillSwitch(enable: boolean)\nEnables or disables the kill switch.\n\n---\n\n## 🔔 Events\n\nUse `addListener` and `removeListener` to handle events:\n\n### 📡 1. onConnectionStatusChanged\nTriggered when VPN connection status changes.\n- Payload: `status` (e.g., `connected`, `disconnected`, `error`).\n\n### ⚠️ 2. onError\nTriggered when an error occurs.\n- Payload: `errorCode` and `errorMessage`.\n\n### 🔄 3. onServerSwitched\nTriggered when the VPN server is switched.\n- Payload: `newServerAddress`.\n\n### 📊 4. onPingResult\nTriggered when a ping operation completes.\n- Payload: `subscriptionIndex`, `serverIndex`, and `latencyInMs`.\n\n### 🔑 5. onSubscriptionLoaded\nTriggered when a subscription is loaded successfully.\n- Payload: `subscriptionDetails`.\n\n### 📈 6. onDataUsageUpdated\nTriggered periodically with updated data usage statistics.\n- Payload: `dataUsed` and `dataRemaining`.\n\n### 📌 7. onRoutingRulesApplied\nTriggered when routing rules are applied.\n- Payload: Array of `RoutingRule`.\n\n### 🚨 8. onKillSwitchTriggered\nTriggered when the kill switch is activated.\n\n---\n\n## 📂 Type Definitions\n\n```typescript\ntype ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';\n\ninterface Server {\n  address: string;\n  latency: number;\n  location: string;\n  isPreferred: boolean;\n}\n\ninterface RoutingRule {\n  appName?: string;\n  domain?: string;\n  action: 'block' | 'allow' | 'proxy';\n}\n\ninterface PingResult {\n  subscriptionIndex: number;\n  serverIndex: number;\n  latencyInMs: number;\n}\n\ninterface SubscriptionDetails {\n  expiryDate: string;\n  dataLimit: number;\n  usedData: number;\n}\n```\n\n---\n\n## 📜 License\n\nThis project is licensed under the **VPNclient Extended GNU General Public License v3 (GPL v3)**. See [LICENSE.md](LICENSE.md) for details.\n\n⚠️ **Note:** By using this software, you agree to comply with additional conditions outlined in the [VPNсlient Extended GNU General Public License v3 (GPL v3)](LICENSE.md)\n\n## 💬 Support\nFor issues or questions, please open an issue on our GitHub repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpnclient%2Fvpnclient-engine-react-native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvpnclient%2Fvpnclient-engine-react-native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpnclient%2Fvpnclient-engine-react-native/lists"}