react-native-wechat-lib wraps the WeChat SDKs, and its npm tag lags its source

The version gap is the first thing to understand

react-native-wechat-lib provides WeChat SDK support for React Native projects, bridging the Android SDK 6.8.20 and the iOS SDK 2.0.

The warning is in the notes section, and it is unambiguous. If your iOS app needs the WeChat SDK without the payment function, use the NPM package with the `-notpay` suffix. The latest code version is 3.0.x, but the npm latest version is only 1.1.26 for now, because 3.0.x is still in development and some functionality has not been tested. If you need the 3.0.x version, add the version number `[email protected]` in your package.json, and before switching you should be clear about the risks, since that version is a development build. The author says a 3.0.x release will come as soon as possible.

So there are three states in play. The published npm package at 1.1.26, which is the old stable line with the older SDKs. The 3.0.x source line, which the package file describes as version 3.0.4 and which you have to opt into by pinning the version explicitly. And the `-notpay` variants for iOS.

The roadmap shows the same split in checklist form. The 3.0.x line has React Native 70, Android SDK 6.8.20 and iOS SDK 2.0 checked off, with iOS SDK 2.0 with no payment function still unchecked. The 1.1.x line has React Native 60, Android SDK 5.5.6 and iOS SDK 1.8.7.1 done, including the no-payment variant.

That last checkbox is the detail that decides whether you can use the current line. If you need WeChat Pay on iOS, the newest SDK build in this project does not have it.

Installing is npm, and the old autolinking step is deprecated

The installation section gives the npm route, and it shows the version split directly in the commands:

npm install react-native-wechat-lib --save
npm install [email protected] --save

The second command is the one that reaches the 3.0.x line, and the comment in the source marks the third command as deprecated from 3.0.0, which is the `react-native link` invocation. That is the old autolinking step, and it is gone in the newer line, which means the iOS and Android setup documents under docs/ are now the required path rather than the optional one.

For source installs, the repository documents a clone-and-link flow:

git clone https://github.com/little-snow-fox/react-native-wechat-lib
cd react-native-wechat-lib
npm link
cd ../my-project
npm link react-native-wechat-lib

and a version-pinned variant of the same, which clones the repository, checks out the 1.1.x branch with `git checkout 1.1.x`, and then repeats the same link steps. That is the route to take if you need to work against the older line, since the published npm tag and the branches are not the same thing.

The getting started section then points to three things: the iOS installation document, the Android installation document, and the example project in the example/ directory.

The example project is a full React Native app rather than a snippet. It has its own android/ and ios/ directories, a Gemfile and a .ruby-version, a metro.config.js, a react-native.config.js, a babel.config.js, and its own yarn.lock. That is what a native module with a real native dependency looks like, and it is the only reliable way to see what the setup requires before you commit to it.

Registration is one call, and the rest of the API mirrors WeChat's own names

The library supports TypeScript, and you receive results with a Promise or with async/await. The interface names and parameters are kept as close as possible to Tencent's own documentation, with the exception that nested objects become flat, and you can consult the WeChat documentation for more detail.

That naming choice is worth appreciating. If you are porting a WeChat integration from native Android or iOS, or you have read the WeChat platform documentation, the method names here are the ones you already know.

Registration is the first call:

import * as WeChat from 'react-native-wechat-lib';

WeChat.registerApp('appid', 'universalLink');

The `appid` is the one you get from the WeChat dashboard, and the call returns a Boolean explaining whether your application is registered. The documentation says this method should be called once globally, which is a hint that the registration state is process-wide rather than per call site.

The capability checks around it are the ones you need before anything else. `isWXAppInstalled()` returns a Boolean indicating whether the WeChat app is installed on the device. `isWXAppSupportApi()` returns a Boolean containing the result of checking whether WeChat supports opening a URL. `getApiVersion()` returns a String with the WeChat SDK API version. And `openWXApp()` opens the WeChat app from your application, returning a Boolean.

The pattern is that everything returns a plain value rather than a wrapped result object, and the error cases are handled by the auth and share methods instead, which return an object with an `errCode` and `errStr` pair.

Login has two paths, and one of them takes a secret into the app

The standard login is `sendAuthRequest([scope[, state]])`, which sends an authentication request. The `scope` is an array or string of scopes, and `state` is the OAuth2 state. The result is an object with seven documented fields.

There is `errCode` as a Number, which is the error code, and `errStr` as a String for the error message if any error occurred. Then `openId` as a String, `code` as a String for the authorization code, `url` as the URL string, and `lang` for the user language and `country` for the user country.

The second path is `authByScan([scope, nonceStr, onQRGet])`, which is the QR code scan login. The parameters are the `appId` you get from the WeChat dashboard, the `appSecret` you get from the WeChat dashboard, and `onQRGet`, a function of type String to void. The example:

const ret = await WeChat.authByScan(WeiXinId, WeiXinSecret, (qrcode) => {
  console.log(qrcode)
});  
console.log('登录信息', ret);

The callback fires when the QR code is obtained, so you display it and the callback only completes after the user has scanned and logged in. The returned fields are `errCode` and `errStr` as before, plus `nickname` for the WeChat nickname, `headimgurl` for the WeChat avatar link, `openid` and `unionid`.

There is a security point in that signature that deserves attention, and it is not a flaw in the library but a consequence of how WeChat's scan login works. The `appSecret` is passed into the mobile application, where a user can read it off the device. The documentation links the WeChat official documentation for login via scan as a reference. If you use this path, the secret is on the handset, and that is a decision your threat model has to account for.

Sharing takes a scene number that decides where the content lands

The share methods are variations on one shape, and the shape is what makes them easy to use.

`ShareText(ShareTextMetadata)` shares text. The metadata has a `text` String for the content and a `scene` Number for where to share, with 0 for a session, 1 for the Moments feed and 2 for favourites. The return has `errCode`, where 0 means authorisation succeeded, and `errStr` for any error.

import * as WeChat from 'react-native-wechat-lib';

WeChat.shareText({
  text: 'Text content.',
  scene: 0,
});

`ShareImage(ShareImageMetadata)` takes an `imageUrl` String and the same `scene` Number, with a remote URL:

import * as WeChat from 'react-native-wechat-lib';

WeChat.shareImage({
  imageUrl: 'https://google.com/1.jpg',
  scene: 0,
});

`ShareLocalImage(ShareImageMetadata)` has the same metadata shape, for a local image.

`ShareFile(ShareFileMetadata)` shares a file rather than an image. The metadata has a `url` String, where a remote file starts with http and a local file is an absolute path such as /storage/emulated/0/Android/xxx, a `title` String for the file title, and a `scene` Number for the destination, where the documented options are 0 for a session.

The one implementation note is about the Android side: sharing a local file on Android requires some configuration of the project, and the Android installation document has a section on it. That is the kind of platform difference that a bridge library cannot hide, because the underlying SDKs differ, and it is the sort of thing you find out during integration if you do not read the setup notes first.

What the package actually ships, and who maintains it

The package file describes the build outputs, and they tell you what kind of module this is.

The `main` field points at `lib/commonjs/index`, the `module` field at `lib/module/index`, and the `types` at `lib/typescript/index.d.ts`, which is the standard react-native-builder-bob layout of a library that ships CommonJS, ES modules and type declarations built from the same source. The `react-native` and `source` fields both point at `src/index`, so Metro bundles the TypeScript source directly in development while consumers of the published package get the compiled variants.

The `files` list is the interesting part, because it is the whole native surface: `src`, `lib`, `android`, `ios`, `cpp`, and `*.podspec`, with a series of exclusions for build output, gradle directories, local properties, tests, fixtures, mocks and dotfiles. The `cpp` entry is there because the iOS SDK needs a native shim, and the podspec is what CocoaPods picks up.

The tooling is conventional for a React Native library. `bob build` does the build via the prepack script, `release-it` with the conventional-changelog plugin handles releases, jest runs the tests, tsc with noEmit does the typecheck, and eslint with the community config lints. Lefthook manages the git hooks, with commitlint and the conventional config.

The maintenance situation is the thing to weigh. The project states that it was initiated by little-snow-fox, and asks for pull requests, saying that maintaining it alone is a lot of work. The last push was on 2026-10-19 and the release tags are v3.0.0 from 2023-01-13 and v1.1.26 from the same day, with v1.1.15 from 2020. The primary language is listed as Java, which reflects the Android side of the bridge, and the licence is MIT.

Editorial conclusion

Adopt react-native-wechat-lib if you are shipping a React Native app that needs WeChat login or sharing and you are prepared to pin a specific version and follow the iOS and Android setup documents, because there is no autolinking-free path and the payment function is missing from the iOS SDK build the project ships. Skip it if you need a package with a stable published release today, since the npm tag is well behind the source and the newer line is marked as untested, or if you want a maintained upstream. Verify first which npm version you actually get, whether your iOS app needs the no-payment variant, and that the Android and iOS setup steps in docs/ are followed, because local file sharing on Android in particular needs extra project configuration.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. little-snow-fox/react-native-wechat-lib on GitHub
4. README
5. Releases