react-native-versionkit

A lightweight, zero-native-dependency React Native SDK for displaying your app version in a clean, formatted badge or inline text. Works with Expo and bare React Native out of the box.

v1.2.3

Features

• ✅ Formats version as v1.0.0 automatically
• ✅ <VersionBadge /> — pill badge with top / bottom positioning
• ✅ <VersionText /> — inline version text for Settings / About screens
• ✅ useAppVersion() — hook returning version + parsed semver parts
• ✅ Auto-detects version from expo-constants or react-native-device-info
• ✅ Zero required native dependencies
• ✅ Full TypeScript support

Installation

npm install react-native-versionkit
# or
yarn add react-native-versionkit

Expo projects (recommended)

npx expo install expo-constants

Bare React Native projects

npm install react-native-device-info
cd ios && pod install

Neither is required if you pass the version manually as a prop.

Quick Start

Option A — Auto-detect (Expo)

import { VersionBadge, useAppVersion } from 'react-native-versionkit';

export default function HomeScreen() {
  const { version } = useAppVersion();

  return (
    <View style={{ flex: 1 }}>
      <Text>My App</Text>
      <VersionBadge version={version} position="bottom" overlay />
    </View>
  );
}

Option B — Manual version (zero dependencies)

import { VersionBadge } from 'react-native-versionkit';

<VersionBadge version="1.2.3" position="top" />

Option C — Inline text (Settings / About screen)

import { VersionText, getFormattedVersion } from 'react-native-versionkit';

<VersionText version={getFormattedVersion()} />
// renders: "v1.2.3"

API Reference

<VersionBadge />

| Prop | Type | Default | Description | |------|------|---------|-------------| | version | string | required | Raw version string e.g. "1.2.3" | | position | 'top' \| 'bottom' | 'bottom' | Badge vertical placement | | overlay | boolean | false | Absolute position over parent | | containerStyle | StyleProp<ViewStyle> | — | Outer container style | | badgeStyle | StyleProp<ViewStyle> | — | Pill badge style | | textStyle | StyleProp<TextStyle> | — | Version text style | | testID | string | 'react-native-versionkit-badge' | Test ID |

<VersionText />

| Prop | Type | Default | Description | |------|------|---------|-------------| | version | string | required | Raw version string | | prefix | string | 'v' | Prefix character(s) | | style | StyleProp<TextStyle> | — | Text style | | testID | string | 'react-native-versionkit-text' | Test ID |

useAppVersion(manualVersion?)

const { version, formatted, major, minor, patch } = useAppVersion();
// version   → "1.2.3"
// formatted → "v1.2.3"
// major     → 1
// minor     → 2
// patch     → 3

Pass a string to override auto-detection:

const { formatted } = useAppVersion('2.0.0');

Utilities

import {
  getVersion,          // → "1.2.3"
  getFormattedVersion, // → "v1.2.3"
  formatVersion,       // formatVersion("1.2.3") → "v1.2.3"
  parseVersion,        // parseVersion("1.2.3") → { major:1, minor:2, patch:3 }
} from 'react-native-versionkit';

Custom Styling Examples

Dark themed badge

<VersionBadge
  version={version}
  position="bottom"
  overlay
  badgeStyle={{ backgroundColor: '#1a1a2e', borderRadius: 6 }}
  textStyle={{ color: '#00ff88', fontWeight: '800', fontSize: 12 }}
/>

Settings screen row

<View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
  <Text>App Version</Text>
  <VersionText
    version={version}
    style={{ color: '#888', fontSize: 14 }}
  />
</View>

Version Resolution Order

| Priority | Method | Requires | |----------|--------|----------| | 1st | expo-constants | expo-constants installed | | 2nd | react-native-device-info | react-native-device-info installed | | Fallback | "0.0.0" + console warning | Nothing |

Roadmap

• [x] Phase 1 — Version Badge & Text components
• [ ] Phase 2 — <ChangelogSheet /> — bottom sheet with "What's New"
• [ ] Phase 2 — First-launch detection (AsyncStorage)
• [ ] Phase 2 — changelog.json spec + CLI generator from git commits

Contributing

See the contributing guide to learn how to contribute.

License

MIT