@nauverse/expo-stable-id

Persistent, cross-device user identifier for React Native/Expo. Port of StableID (Swift) to the Expo ecosystem, big thanks to him for that awesome lib!

How it works

expo-stable-id provides a persistent user identifier using dual storage:

• Cloud: @nauverse/expo-cloud-settings (iCloud KVS on iOS, future Android support) - syncs across devices
• Local: expo-secure-store (Keychain on iOS, Android Keystore) - persists across app reinstalls

The ID is generated once and persisted to both storages. On subsequent launches, the stored ID is read back. When iCloud syncs a new ID from another device, the local copy is updated.

Installation

npx expo install @nauverse/expo-stable-id @nauverse/expo-cloud-settings expo-secure-store expo-crypto

Config Plugin

Add to your app.config.ts / app.json:

export default {
  plugins: ['@nauverse/expo-stable-id'],
};

This adds the iCloud KVS entitlement required for cloud sync. Optionally pass a custom container:

export default {
  plugins: [
    ['@nauverse/expo-stable-id', { containerIdentifier: 'com.example.shared' }],
  ],
};

Usage

React Hooks (Recommended)

Note: StableIdProvider does not require CloudSettingsProvider from @nauverse/expo-cloud-settings as an ancestor. Internally it uses the functional API (getString, setString, addChangeListener) from @nauverse/expo-cloud-settings directly. If your app also uses CloudSettingsProvider for its own React hooks (useCloudSetting*), both providers are independent and can be placed in any order.

import { StableIdProvider, useStableId } from '@nauverse/expo-stable-id';

function App() {
  return (
    <StableIdProvider>
      <MyComponent />
    </StableIdProvider>
  );
}

function MyComponent() {
  const [id, { identify, generateNewId }] = useStableId();

  return (
    <View>
      <Text>Stable ID: {id ?? 'Loading...'}</Text>
      <Button title="New ID" onPress={() => generateNewId()} />
      <Button title="Set Custom" onPress={() => identify('user-123')} />
    </View>
  );
}

Provider Config

import { StandardGenerator, ShortIDGenerator } from '@nauverse/expo-stable-id';

// Use short 8-char IDs instead of UUIDs
<StableIdProvider config={{ generator: new ShortIDGenerator() }}>

// Provide a known ID, force it even if one exists
<StableIdProvider config={{ id: 'known-user-id', policy: 'forceUpdate' }}>

// Provide a fallback ID, prefer any stored value
<StableIdProvider config={{ id: 'fallback-id', policy: 'preferStored' }}>

Functional API

import {
  configure,
  getId,
  identify,
  generateNewId,
  isConfigured,
  hasStoredId,
  addChangeListener,
  setWillChangeHandler,
} from '@nauverse/expo-stable-id';

// Initialize (call once at app startup)
const id = await configure();

// Or with options
const id = await configure({
  id: 'fallback-id',
  policy: 'preferStored',
  generator: new ShortIDGenerator(),
});

// Read current ID (sync, from cache)
const currentId = getId();

// Change ID
identify('new-user-id');

// Generate a new random ID
const newId = generateNewId();

// Check state
isConfigured(); // boolean
await hasStoredId(); // boolean

// Listen for changes
const subscription = addChangeListener((event) => {
  console.log(`ID changed: ${event.previousId} -> ${event.newId} (${event.source})`);
});
subscription.remove();

// Intercept changes before they apply (identify, generateNewId, cloud sync)
setWillChangeHandler((currentId, candidateId) => {
  // Return modified ID, or null to accept candidate as-is
  return candidateId;
});

Real-World Example: Shared ID for PostHog + RevenueCat

Use the same stable ID across your analytics and payment provider so user events are always linked:

import { StableIdProvider, useStableId } from '@nauverse/expo-stable-id';
import PostHog from 'posthog-react-native';
import Purchases from 'react-native-purchases';
import { useEffect } from 'react';

function App() {
  return (
    <StableIdProvider>
      <IdentifyProviders />
      {/* rest of your app */}
    </StableIdProvider>
  );
}

function IdentifyProviders() {
  const [id] = useStableId();

  useEffect(() => {
    if (!id) return;

    // Same ID in both services
    PostHog.identify(id);
    Purchases.logIn(id);
  }, [id]);

  return null;
}

ID Generators

| Generator | Output | Example | |-----------|--------|---------| | StandardGenerator (default) | UUID v4 | a1b2c3d4-e5f6-4789-abcd-ef0123456789 | | ShortIDGenerator | 8-char alphanumeric | xK9mP2nQ |

Custom generators implement the IDGenerator interface:

import type { IDGenerator } from '@nauverse/expo-stable-id';

const myGenerator: IDGenerator = {
  generate: () => `prefix-${Date.now()}`,
};

Policies

| Policy | Behavior | |--------|----------| | 'forceUpdate' (default) | Always use the provided id (if given) | | 'preferStored' | Use stored ID if available, fall back to provided id |

Platform Support

| Feature | iOS | Android | |---------|-----|---------| | Local storage (Keychain/Keystore) | Yes | Yes | | Cloud sync (iCloud KVS) | Yes | Coming soon | | ID generation | Yes | Yes |

API Reference

Functional API

| Function | Returns | Description | |----------|---------|-------------| | configure(config?) | Promise<string> | Initialize and get/create stable ID | | getId() | string \| null | Current cached ID (sync) | | identify(id) | void | Set a specific ID | | generateNewId() | string | Generate and persist a new ID | | isConfigured() | boolean | Whether configure() has been called | | hasStoredId() | Promise<boolean> | Whether an ID exists in storage | | addChangeListener(cb) | { remove: () => void } | Subscribe to ID changes | | setWillChangeHandler(fn) | void | Intercept all ID changes before they apply |

React API

| Export | Description | |--------|-------------| | StableIdProvider | Context provider, call configure() internally | | useStableId() | [id, { identify, generateNewId }] |

Types

type IDPolicy = 'preferStored' | 'forceUpdate';
type ChangeSource = 'cloud' | 'manual';

interface IDGenerator {
  generate(): string;
}

interface StableIdConfig {
  readonly id?: string;
  readonly generator?: IDGenerator;
  readonly policy?: IDPolicy;
}

interface StableIdChangeEvent {
  readonly previousId: string | null;
  readonly newId: string;
  readonly source: ChangeSource;
}

Feature Mapping from StableID (Swift)

| StableID (Swift) | expo-stable-id | Notes | |------------------|----------------|-------| | StableID.configure(id?, generator, policy) | configure(config?) | Same semantics | | StableID.id | getId() / useStableId()[0] | Sync cached read | | StableID.identify(id:) | identify(id) | Writes both storages | | StableID.generateNewID() | generateNewId() | Uses configured generator | | StableID.isConfigured | isConfigured() | Static check | | StableID.hasStoredID | hasStoredId() | Checks both storages | | StableID.set(delegate:) | addChangeListener() + setWillChangeHandler() | JS-idiomatic | | StandardGenerator | StandardGenerator | UUID v4 | | ShortIDGenerator | ShortIDGenerator | 8-char alphanumeric |

License

MIT