Skip to main content

React Native Peer Dependency Versioning Strategy

  • Status: Proposed
  • Deciders: Abyss Mobile Team
  • Date: 2025-05-07

Context​

The @uhg-abyss/mobile package currently supports React Native versions >=0.70.0 <1 as a peer dependency. Without a clear versioning policy, we face several challenges:

  1. Unclear Support Boundaries: Teams upgrading React Native don't know which versions are officially supported or tested
  2. Maintenance Burden: Supporting too many React Native versions increases our testing surface and maintenance overhead
  3. Breaking Changes: No clear guidance on when we can drop support for older React Native versions or the old architecture
  4. Semver Ambiguity: Uncertainty about whether React Native peer dependency updates constitute breaking changes in Abyss
  5. Multiple React Native Dependencies: Other React Native peer dependencies (react-native-svg, react-native-video, react-navigation, etc.) lack a coordinated versioning strategy

Currently, @uhg-abyss/mobile has the following React Native-related peer dependencies:

{
  "react": "^18.0.0 || ^19.0.0",
  "react-native": ">=0.70.0 <1",
  "react-native-safe-area-context": ">=3.0.0",
  "react-native-screens": ">=2.0.0",
  "react-native-svg": ">=12.0.0",
  "react-native-video": ">=5.0.0",
  "@react-navigation/bottom-tabs": ">=5.0.0",
  "@react-navigation/native": ">=5.0.0",
  "@react-navigation/native-stack": ">=5.0.0"
}

As the design system team, establishing a clear versioning strategy reduces friction for consuming teams and keeps our maintenance burden sustainable.

Decision​

We will adopt a rolling support window strategy for React Native peer dependencies with the following principles:

1. React Native Version Support Policy​

Support Window: We will officially support the latest 5 major/minor React Native versions at any given time.

  • Rationale: React Native releases approximately every 2 months (6-8 weeks). Supporting 5 versions provides teams with a reasonable upgrade window of 8-10 months while keeping our testing matrix manageable
  • Example: If the latest RN version is 0.85, we support 0.85, 0.84, 0.83, 0.82, and 0.81
  • Current Support (as of May 2026): React Native 0.81.0 through 0.85.0
  • Old Architecture: The old architecture was removed by default in React Native 0.82. Abyss can drop old architecture support when our minimum supported version reaches 0.84 (expected ~October 2026 when RN 0.88 releases)

2. Peer Dependency Range Strategy​

Peer Dependency Declaration: Use a minimum version with upper bound approach:

{
  "react-native": ">=0.81.0 <1"
}
  • The minimum version reflects the oldest version in our support window
  • The upper bound prevents installation with untested major versions
  • This range will be updated every 2-3 months as we drop support for older versions (aligned with RN's release cadence)

3. Semver and Breaking Changes​

Dropping RN Support with Deprecation Warnings: Dropping support for an older React Native version can be done in a minor version bump if proper deprecation warnings were provided in advance.

  • Rationale: With a 2-3 month deprecation period and clear documentation, teams have adequate notice to upgrade.
  • Requirements:
    • Must provide 2-3 months advance notice in documentation
    • Should add console warnings (if feasible) 1 month before dropping support
    • Must be clearly documented in release notes
  • Exception: If dropping support for multiple RN versions at once or making other significant breaking changes, use a major version bump

Adding New RN Support is Not Breaking: Supporting newer React Native versions can be done in minor or patch releases.

  • Rationale: Existing consumers are not affected; they can upgrade RN at their own pace

Aligned Strategy: All React Native-related peer dependencies will follow the same rolling support window:

  • react-native-svg: Support versions compatible with our RN support window
  • react-native-video: Support versions compatible with our RN support window
  • react-navigation/*: Support versions compatible with our RN support window
  • react-native-safe-area-context: Support versions compatible with our RN support window
  • react-native-screens: Support versions compatible with our RN support window

Dependency Version Ranges: Use permissive ranges that align with our RN support window:

{
  "react-native-svg": ">=13.0.0",
  "react-native-video": ">=6.0.0",
  "@react-navigation/native": ">=6.0.0"
}

5. Testing Strategy​

Latest Version Testing: We will test against the latest supported React Native version in CI:

  • Rationale: React Native upgrades typically require more than just version bumps (native code changes, dependency updates, configuration changes). Testing multiple versions via matrix builds is not practical given this complexity
  • Latest Version Only: CI will test against the maximum supported RN version (e.g., 0.85.0)
  • Architecture Testing: Focus testing on the new architecture only. Since old architecture support will be dropped in ~5 months (October 2026), building out dual-architecture testing infrastructure is not a worthwhile investment
  • Backward Compatibility: While we only test the latest version, we will maintain peer dependency ranges that allow older versions and rely on semantic versioning and React Native's backward compatibility

Implementation Approach:

  • Test against latest supported React Native version in CI
  • Focus on smoke tests and critical user flows rather than exhaustive testing
  • Leverage React Native's upgrade helper and breaking change logs when upgrading
  • Test exclusively on new architecture to align with React Native's direction
  • When issues are reported on older supported versions, evaluate on a case-by-case basis

6. Communication and Documentation​

Public Documentation: Maintain a clear "Supported Versions" page in our documentation site:

  • List currently supported React Native versions
  • Show compatibility matrix for all React Native peer dependencies
  • Provide upgrade guidance and migration notes
  • Include deprecation warnings for versions approaching end-of-support

Deprecation Timeline: When planning to drop support for an RN version:

  1. 2-3 months before: Announce deprecation in documentation (when version falls to 6th oldest)
  2. 1 month before: Add console warnings for deprecated RN versions (if feasible)
  3. At release: Drop support and publish minor version

Note: Given React Native's 2-month release cadence, we will typically drop support for the oldest version every 2-4 months (every 1-2 RN releases).

Versioned Documentation: Since Abyss documentation is versioned, each Abyss version will maintain its own "Supported React Native Versions" page that accurately reflects which RN versions are compatible with that specific Abyss release. This provides a single source of truth for each Abyss version.

Release Notes: Release notes should only mention React Native version support changes when:

  • Support for a new React Native version is added
  • Support for an older React Native version is dropped

Regular releases that don't change the RN support window do not need to mention React Native versions in release notes.

7. Initial Adoption Plan​

Since this policy represents a significant jump from the current >=0.70.0 <1 peer dependency to >=0.81.0 <1, we will provide a transition period for consuming teams:

  1. Announce the new policy — Publish the supported versions documentation and communicate via our normal channels (Teams, release notes)
  2. Grace period (3 months) — Teams on RN versions below 0.81.0 have 3 months to upgrade before we enforce the new minimum
  3. Deprecation warnings — During the grace period, add console warnings for teams on unsupported versions (if feasible) so they're aware
  4. Enforce — After the grace period, publish the Abyss version with the updated >=0.81.0 peer dependency

Most teams are already on RN 0.81+, so the grace period is largely a formality. However, it ensures no team is caught off guard by the change.

Alternatives Considered​

Alternative 1: Support Only Latest React Native Version​

Advantages:

  • Minimal testing burden
  • Always on latest features and fixes
  • Simplest maintenance

Disadvantages:

  • Forces teams to upgrade RN immediately when we release
  • Creates significant friction and potential blockers
  • Not realistic for enterprise teams with slower upgrade cycles
  • Rejected: Too disruptive for consuming teams

Alternative 2: Support All React Native Versions Indefinitely​

Advantages:

  • Maximum flexibility for consuming teams
  • No breaking changes for version drops

Disadvantages:

  • Unsustainable testing matrix
  • Prevents us from using newer RN features
  • Accumulates technical debt
  • Rejected: Unsustainable maintenance burden

Alternative 3: Support Based on React Native LTS Releases​

Advantages:

  • Aligns with official React Native support policy
  • Clear external signal for support windows

Disadvantages:

  • React Native doesn't have a formal LTS program
  • Would require waiting for RN community to establish LTS
  • Rejected: No official RN LTS exists currently

Alternative 4: Fixed Time-Based Support (e.g., 18 months)​

Advantages:

  • Predictable support timeline
  • Clear communication to teams

Disadvantages:

  • Doesn't account for varying RN release cadences
  • Could result in supporting too many or too few versions
  • More complex to track and communicate
  • Rejected: Version-based window is simpler and more predictable

Consequences​

Positive​

  • Clear Expectations: Teams know exactly which React Native versions are supported
  • Sustainable Maintenance: Limited testing matrix keeps our CI/CD manageable
  • Upgrade Confidence: Teams can upgrade React Native knowing Abyss compatibility
  • Reduced Support Burden: Clear boundaries limit support requests for unsupported versions
  • Coordinated Dependencies: All React Native peer dependencies follow the same strategy
  • Proactive Communication: Deprecation timeline gives teams advance notice

Negative​

  • Version Churn: Dropping RN support every 2-4 months means frequent minor version bumps
  • Testing Gaps: Only testing the latest RN version means older supported versions may have undiscovered issues
  • Documentation Overhead: Requires maintaining compatibility matrices and upgrade guides
  • Potential Team Friction: Teams on older RN versions may be blocked from Abyss upgrades
  • Coordination Required: Need to monitor React Native release schedule and plan accordingly

Mitigation Strategies​

  • Advance Communication: 2-3 month deprecation notice gives teams time to plan upgrades
  • Selective Testing: Focus on critical paths rather than exhaustive coverage
  • Automated Monitoring: Set up alerts for new React Native releases
  • Case-by-Case Fixes: Address issues reported on older supported versions reactively

Future Considerations​

  • Community Feedback: Monitor feedback from consuming teams and adjust support window if needed (e.g., expand to 6 versions or reduce to 4 versions based on team upgrade patterns)
  • React Native LTS: If React Native establishes an official LTS program, reevaluate our strategy to align with it

Follow-Up Stories​

Based on this ADR, the following implementation stories are needed:

  1. Update Documentation

    • Create "Supported React Native Versions" page in docs site
    • Add compatibility matrix for all React Native peer dependencies
    • Document upgrade process and migration guidelines
    • Add deprecation policy to developer documentation

  2. Update CI Testing for Latest React Native Version

    • Update CI to test against latest supported RN version (currently 0.85.0)
    • Configure test environment for new architecture only
    • Set up automated alerts for CI failures
    • Document process for upgrading to new RN versions as they release

  3. Update Peer Dependencies

    • Review and update all React Native peer dependency ranges
    • Ensure consistency across react-native-svg, react-native-video, react-navigation, etc.
    • Update package.json with new minimum version (0.81.0)
    • Validate peer dependency warnings with npm/pnpm

  4. Create Deprecation Communication Process

    • Set up calendar reminders for React Native release monitoring
    • Create template for deprecation announcements
    • Establish process for console warnings (if feasible)
    • Define communication channels (Teams, email, release notes)

  5. Establish Version Monitoring

    • Set up automated monitoring for new React Native releases
    • Create process for evaluating new RN versions for compatibility
    • Define criteria for when to add support for new RN versions
    • Document decision-making process for version support

References​

Table of Contents