Skip to content

Commit b8a59c0

Browse files
AlshehriAli0AlshehriAli0
committed
chore: enhance README with improved formatting and detailed features
1 parent 6269e01 commit b8a59c0

2 files changed

Lines changed: 191 additions & 90 deletions

File tree

‎README.md‎

Lines changed: 89 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,116 @@
1-
# react-native-nitro-version-check
1+
<h1 align="center">
2+
react-native-nitro-version-check
3+
</h1>
24

3-
A React Native module to check app version info, built with [Nitro Modules](https://github.com/mrousavy/nitro).
5+
<p align="center">
6+
<b>A fast, modern version-checking library for React Native, powered by <a href="https://github.com/mrousavy/nitro">Nitro Modules</a>.</b>
7+
</p>
8+
9+
<p align="center">
10+
A drop-in replacement for the unmaintained <a href="https://github.com/kimxogus/react-native-version-check"><code>react-native-version-check</code></a> — rewritten from scratch with <a href="https://github.com/mrousavy/nitro">Nitro Modules</a>.
11+
</p>
12+
13+
<br />
14+
15+
## Features
16+
17+
- ⚡ **Synchronous access** to version, build number, package name, and country
18+
- 🏪 **Store version lookup** from the App Store or Play Store
19+
- 🔍 **Granular update checks** — major, minor, or patch
20+
- 📦 **Install source detection** — TestFlight, App Store, Play Store, or sideloaded
21+
- 🪶 **Tiny footprint** — pure Swift on iOS, Kotlin on Android
22+
23+
## Performance
24+
25+
Benchmarked against [`react-native-version-check`](https://github.com/kimxogus/react-native-version-check). 100,000 iterations averaged over 5 runs on an iPhone 12:
26+
27+
| Method | Speedup |
28+
|--------|---------|
29+
| `getAllInfo` | **~3.1x faster** |
30+
| `packageName` | **~1.6x faster** |
31+
| `version` | **~1.6x faster** |
32+
| `buildNumber` | **~1.6x faster** |
33+
| `getCountry` | **~3.1x faster** |
434

535
## Installation
636

737
```sh
8-
bun add react-native-nitro-version-check react-native-nitro-modules
38+
npm i react-native-nitro-version-check react-native-nitro-modules
39+
```
40+
41+
For Expo projects, run prebuild:
42+
```sh
43+
npx expo prebuild
44+
```
45+
46+
For bare React Native projects:
47+
```sh
48+
cd ios && pod install
949
```
1050

1151
## Usage
1252

13-
```tsx
14-
import { VersionCheck } from "react-native-nitro-version-check";
53+
```ts
54+
import { VersionCheck, getCountry, getStoreUrl, getLatestVersion, needsUpdate } from 'react-native-nitro-version-check'
1555

16-
// Static properties
17-
VersionCheck.version; // "1.0.0"
18-
VersionCheck.buildNumber; // "42"
19-
VersionCheck.packageName; // "com.example.app"
20-
VersionCheck.getCountry(); // "US"
56+
// Sync properties
57+
VersionCheck.version // "1.2.0"
58+
VersionCheck.buildNumber // "42"
59+
VersionCheck.packageName // "com.example.app"
60+
VersionCheck.installSource // "appstore" | "testflight" | "playstore" | undefined
61+
getCountry() // "US"
2162

22-
// Async methods
23-
const storeUrl = await VersionCheck.getStoreUrl();
24-
const latest = await VersionCheck.getLatestVersion();
63+
// Async
64+
const url = await getStoreUrl() // App Store / Play Store URL
65+
const latest = await getLatestVersion() // "1.3.0"
2566

26-
if (await VersionCheck.needsUpdate()) {
27-
Linking.openURL(await VersionCheck.getStoreUrl());
67+
if (await needsUpdate()) {
68+
Linking.openURL(await getStoreUrl())
2869
}
29-
```
30-
31-
Or import individually:
3270

33-
```tsx
34-
import { version, buildNumber, getCountry, needsUpdate } from "react-native-nitro-version-check";
71+
// Only prompt for major updates
72+
if (await needsUpdate({ level: 'major' })) {
73+
// 1.x → 2.x
74+
}
3575
```
3676

3777
## API
3878

39-
### Properties
79+
### `VersionCheck`
4080

41-
| API | Type | Description |
42-
|-----|------|-------------|
81+
| Property | Type | Description |
82+
|----------|------|-------------|
4383
| `version` | `string` | App version |
4484
| `buildNumber` | `string` | Build number |
45-
| `packageName` | `string` | Bundle ID / package name |
85+
| `packageName` | `string` | Bundle ID / Application ID |
86+
| `installSource` | `string \| undefined` | `"appstore"` `"testflight"` `"playstore"` or `undefined` |
87+
| `getCountry()` | `string` | Device's 2-letter ISO country code |
88+
| `getStoreUrl()` | `Promise<string>` | App Store / Play Store URL |
89+
| `getLatestVersion()` | `Promise<string>` | Latest version in the store |
90+
| `needsUpdate()` | `Promise<boolean>` | Whether an update is available |
4691

47-
### Methods
92+
### Standalone exports
4893

49-
| API | Returns | Description |
50-
|-----|---------|-------------|
51-
| `getCountry()` | `string` | Current device country code |
94+
Also available as individual named exports:
95+
96+
| Export | Returns | Description |
97+
|--------|---------|-------------|
98+
| `getCountry()` | `string` | Device's 2-letter ISO country code |
5299
| `getStoreUrl()` | `Promise<string>` | App Store / Play Store URL |
53-
| `getLatestVersion()` | `Promise<string>` | Latest version from the store |
54-
| `needsUpdate()` | `Promise<boolean>` | Whether an update is available |
100+
| `getLatestVersion()` | `Promise<string>` | Latest version in the store |
101+
| `needsUpdate(options?)` | `Promise<boolean>` | Whether an update is available |
102+
103+
#### `needsUpdate` options
104+
105+
| Option | Type | Default | Description |
106+
|--------|------|---------|-------------|
107+
| `level` | `"major" \| "minor" \| "patch"` | `"patch"` | Minimum version bump to trigger `true` |
108+
109+
### Utilities
110+
111+
| Function | Returns | Description |
112+
|----------|---------|-------------|
113+
| `compareVersions(v1, v2)` | `-1 \| 0 \| 1` | Compare two semver strings |
55114

56115
## License
57116

‎package/src/index.ts‎

Lines changed: 102 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -5,62 +5,11 @@ import type { VersionCheck as VersionCheckType } from "./specs/Version.nitro";
55

66
const HybridVersionCheck = NitroModules.createHybridObject<VersionCheckType>("VersionCheck");
77

8-
/**
9-
* The current app version.
10-
*
11-
* @platform ios - `CFBundleShortVersionString`
12-
* @platform android - `versionName`
13-
*
14-
* @example
15-
* ```ts
16-
* version // "1.2.0"
17-
* ```
18-
*/
19-
export const version = HybridVersionCheck.version;
20-
21-
/**
22-
* The current app build number.
23-
*
24-
* @platform ios - `CFBundleVersion`
25-
* @platform android - `versionCode`
26-
*
27-
* @example
28-
* ```ts
29-
* buildNumber // "42"
30-
* ```
31-
*/
32-
export const buildNumber = HybridVersionCheck.buildNumber;
33-
34-
/**
35-
* The app's unique identifier.
36-
*
37-
* @platform ios - Bundle ID (e.g. `com.example.app`)
38-
* @platform android - Application ID (e.g. `com.example.app`)
39-
*
40-
* @example
41-
* ```ts
42-
* packageName // "com.example.app"
43-
* ```
44-
*/
45-
export const packageName = HybridVersionCheck.packageName;
46-
47-
/**
48-
* Where the app was installed from, or `undefined` in dev/debug/sideloaded builds.
49-
*
50-
* @platform ios - `"testflight"` | `"appstore"` | `undefined`
51-
* @platform android - `"playstore"` | `undefined` — detects Play Store, Amazon Appstore, Samsung Galaxy Store, Huawei AppGallery, and other store installers
52-
*
53-
* @example
54-
* ```ts
55-
* if (installSource === "testflight") {
56-
* // TestFlight build
57-
* }
58-
* if (!installSource) {
59-
* // dev / sideloaded build
60-
* }
61-
* ```
62-
*/
63-
export const installSource = HybridVersionCheck.installSource;
8+
// Cached at module init — plain JS values, no JSI overhead on repeated access.
9+
const version = HybridVersionCheck.version;
10+
const buildNumber = HybridVersionCheck.buildNumber;
11+
const packageName = HybridVersionCheck.packageName;
12+
const installSource = HybridVersionCheck.installSource;
6413

6514
/**
6615
* Returns the device's current 2-letter ISO country code.
@@ -122,20 +71,113 @@ export const needsUpdate = async (options?: { level?: UpdateLevel }): Promise<bo
12271
};
12372

12473
/**
125-
* Convenience object with cached static properties.
74+
* All version-check APIs in one object.
12675
*
127-
* Properties like `version`, `buildNumber`, `packageName`, and `installSource`
128-
* are read once from native at module init and cached as plain JS values —
129-
* no JSI overhead on repeated access. Methods still call through JSI.
76+
* @example
77+
* ```ts
78+
* VersionCheck.version // "1.2.0"
79+
* VersionCheck.buildNumber // "42"
80+
* VersionCheck.packageName // "com.example.app"
81+
* VersionCheck.getCountry() // "US"
82+
*
83+
* const url = await VersionCheck.getStoreUrl();
84+
* ```
13085
*/
13186
export const VersionCheck = {
87+
/**
88+
* The current app version string.
89+
*
90+
* Read from `CFBundleShortVersionString` on iOS and `versionName` on Android.
91+
* Cached at module init, so repeated reads have zero native overhead.
92+
*
93+
* @example
94+
* ```ts
95+
* VersionCheck.version // "1.2.0"
96+
* ```
97+
*/
13298
version,
99+
/**
100+
* The current build number.
101+
*
102+
* Read from `CFBundleVersion` on iOS and `versionCode` on Android.
103+
* Cached at module init.
104+
*
105+
* @example
106+
* ```ts
107+
* VersionCheck.buildNumber // "42"
108+
* ```
109+
*/
133110
buildNumber,
111+
/**
112+
* The app's unique identifier.
113+
*
114+
* This is the Bundle ID on iOS and the Application ID on Android.
115+
* Cached at module init.
116+
*
117+
* @example
118+
* ```ts
119+
* VersionCheck.packageName // "com.example.app"
120+
* ```
121+
*/
134122
packageName,
123+
/**
124+
* Where the app was installed from, or `undefined` for dev/sideloaded builds.
125+
*
126+
* - iOS: `"appstore"` | `"testflight"` | `undefined`
127+
* - Android: `"playstore"` | `undefined`
128+
*
129+
* @example
130+
* ```ts
131+
* if (VersionCheck.installSource === "testflight") {
132+
* // running a TestFlight build
133+
* }
134+
* ```
135+
*/
135136
installSource,
137+
/**
138+
* Returns the device's current 2-letter ISO country code.
139+
*
140+
* This is a synchronous Nitro call, no `await` needed.
141+
*
142+
* @example
143+
* ```ts
144+
* VersionCheck.getCountry() // "US"
145+
* ```
146+
*/
136147
getCountry,
148+
/**
149+
* Returns the App Store (iOS) or Play Store (Android) URL for this app.
150+
*
151+
* @example
152+
* ```ts
153+
* const url = await VersionCheck.getStoreUrl();
154+
* Linking.openURL(url);
155+
* ```
156+
*/
137157
getStoreUrl,
158+
/**
159+
* Fetches the latest version of this app available in the store.
160+
*
161+
* Queries the iTunes API on iOS and the Play Store on Android.
162+
*
163+
* @example
164+
* ```ts
165+
* const latest = await VersionCheck.getLatestVersion(); // "1.3.0"
166+
* ```
167+
*/
138168
getLatestVersion,
169+
/**
170+
* Checks whether an app update is available by comparing the current
171+
* version against the latest store version.
172+
*
173+
* @example
174+
* ```ts
175+
* if (await VersionCheck.needsUpdate()) {
176+
* const url = await VersionCheck.getStoreUrl();
177+
* Linking.openURL(url);
178+
* }
179+
* ```
180+
*/
139181
needsUpdate: () => HybridVersionCheck.needsUpdate(),
140182
} as const;
141183

0 commit comments

Comments
 (0)