Despia Version Guard

A framework-agnostic solution for conditionally rendering UI elements based on the Despia Native SDK runtime version (window.bundleNumber). Supports React, Vue, Angular, Svelte, and Vanilla JS/Web Components. This allows you to build conditional UI for major version shifts while remaining store-compliant and managing versioning for dynamic Despia apps.

Installation

npm install despia-version-guard

Framework Support

• React (16.8+)
• Vue 3
• Angular (Standalone components)
• Svelte
• Vanilla JS / Web Components

Usage

React

import { VersionGuard } from 'despia-version-guard';

// Only show this feature if version is 21.0.3 or higher
<VersionGuard min_version="21.0.3">
  <NewFeatureComponent />
</VersionGuard>

// Only show this feature if version is 21.0.3 or lower
<VersionGuard max_version="21.0.3">
  <LegacyFeatureComponent />
</VersionGuard>

// Only show this feature if version is between 21.0.0 and 21.0.3 (inclusive)
<VersionGuard min_version="21.0.0" max_version="21.0.3">
  <VersionSpecificFeature />
</VersionGuard>

Vue 3

<template>
  <VersionGuard :min-version="'21.0.3'">
    <NewFeatureComponent />
  </VersionGuard>

  <VersionGuard :max-version="'21.0.3'">
    <LegacyFeatureComponent />
  </VersionGuard>

  <VersionGuard :min-version="'21.0.0'" :max-version="'21.0.3'">
    <VersionSpecificFeature />
  </VersionGuard>
</template>

<script setup lang="ts">
import { VersionGuard } from 'despia-version-guard/vue';
</script>

Angular

import { Component } from '@angular/core';
import { VersionGuardComponent } from 'despia-version-guard/angular';

@Component({
  selector: 'app-feature',
  standalone: true,
  imports: [VersionGuardComponent],
  template: `
    <version-guard [minVersion]="'21.0.3'">
      <new-feature-component />
    </version-guard>

    <version-guard [maxVersion]="'21.0.3'">
      <legacy-feature-component />
    </version-guard>

    <version-guard [minVersion]="'21.0.0'" [maxVersion]="'21.0.3'">
      <version-specific-feature />
    </version-guard>
  `
})
export class FeatureComponent {}

Svelte

<script>
  import VersionGuard from 'despia-version-guard/svelte';
</script>

<VersionGuard minVersion="21.0.3">
  <NewFeatureComponent />
</VersionGuard>

<VersionGuard maxVersion="21.0.3">
  <LegacyFeatureComponent />
</VersionGuard>

<VersionGuard minVersion="21.0.0" maxVersion="21.0.3">
  <VersionSpecificFeature />
</VersionGuard>

Vanilla JS / Web Components

Web Component (Recommended)

<!-- Register the component (only needed once) -->
<script type="module">
  import 'despia-version-guard/vanilla';
</script>

<!-- Use the component -->
<version-guard min-version="21.0.3">
  <div>New Feature</div>
</version-guard>

<version-guard max-version="21.0.3">
  <div>Legacy Feature</div>
</version-guard>

<version-guard min-version="21.0.0" max-version="21.0.3">
  <div>Version-Specific Feature</div>
</version-guard>

Programmatic API

import { createVersionGuard } from 'despia-version-guard/vanilla';

const element = document.getElementById('my-feature');

// Create version guard
const updateVisibility = createVersionGuard({
  minVersion: '21.0.3',
  element: element
});

// Manually check version (optional)
updateVisibility();

Use Cases

1. Major UI Shifts: Show new UI only to users with the required minimum version
2. Deprecation: Hide legacy features when version exceeds maximum
3. Upgrade Prompts: Conditionally show upgrade buttons based on version
4. Store Compliance: Ensure app review compatibility by version-gating major changes
5. Enterprise Reliability: Prevent broken UI when Despia adds new runtime features that old users don't have
6. Progressive Enhancement: Gracefully degrade features for users with older runtimes

How It Works

• The component reads window.bundleNumber from the Despia Native SDK runtime
• It compares the current version with min_version and max_version props
• If the version is outside the specified range, the component returns null (renders nothing)
• If the version is within range (or no constraints are specified), it renders the children wrapped in a div

Version Comparison

Version comparison uses semantic versioning:

• "21.0.2" < "21.0.3" → true
• "21.0.3" == "21.0.3" → true
• "21.0.4" > "21.0.3" → true

Examples

Example 1: Minimum Version Only

// Hide if version is less than 21.0.3
<VersionGuard min_version="21.0.3">
  <div>This only shows on 21.0.3+</div>
</VersionGuard>

If window.bundleNumber is "21.0.2", the content will be hidden.

Example 2: Maximum Version Only

// Hide if version is greater than 21.0.3
<VersionGuard max_version="21.0.3">
  <div>This only shows on 21.0.3 or lower</div>
</VersionGuard>

If window.bundleNumber is "21.0.4", the content will be hidden.

Example 3: Version Range

// Only show for versions between 21.0.0 and 21.0.3 (inclusive)
<VersionGuard min_version="21.0.0" max_version="21.0.3">
  <div>This shows for versions 21.0.0 through 21.0.3</div>
</VersionGuard>

Example 4: Enterprise Use Case - New Despia Runtime Feature

// Despia adds a new feature in runtime 21.0.4
// Hide the feature from old users and show upgrade prompt
<VersionGuard min_version="21.0.4">
  <NewDespiaFeature />
</VersionGuard>

// Show critical upgrade prompt for very old users
<VersionGuard max_version="21.0.1">
  <CriticalUpgradePrompt />
</VersionGuard>

// Show standard upgrade prompt for users who need minor update
{!isVersionInRange(window.bundleNumber, '21.0.4') && 
 isVersionInRange(window.bundleNumber, '21.0.2') && (
  <StandardUpgradePrompt />
)}

This pattern ensures:

• 100% Reliability: Old users never see broken features
• Clear Upgrade Path: Users know when and why to update
• Enterprise-Grade: Critical for apps where users depend on functionality working correctly
• Store Compliance: Prevents app review issues from broken features

API

Component Props / Attributes

| Prop/Attribute | Type | Required | Description | |----------------|------|----------|-------------| | min_version / minVersion / min-version | string | No | Minimum version (inclusive). Content is hidden if current version is less than this. | | max_version / maxVersion / max-version | string | No | Maximum version (inclusive). Content is hidden if current version is greater than this. |

Note: Prop naming varies by framework:

• React: min_version, max_version (snake_case)
• Vue: minVersion, maxVersion (camelCase)
• Angular: minVersion, maxVersion (camelCase)
• Svelte: minVersion, maxVersion (camelCase)
• Web Components: min-version, max-version (kebab-case)

Utility Functions

You can also import utility functions for custom version comparison:

import { compareVersions, isVersionInRange } from 'despia-version-guard';

// Compare two versions
compareVersions("21.0.3", "21.0.2"); // Returns 1 (first is greater)

// Check if version is in range
isVersionInRange("21.0.3", "21.0.0", "21.0.5"); // Returns true

Framework-Specific Imports

// React (default)
import { VersionGuard } from 'despia-version-guard';

// Vue
import { VersionGuard } from 'despia-version-guard/vue';

// Angular
import { VersionGuardComponent } from 'despia-version-guard/angular';

// Svelte
import VersionGuard from 'despia-version-guard/svelte';

// Vanilla JS
import { createVersionGuard, VersionGuardElement } from 'despia-version-guard/vanilla';

Requirements

• Framework: React 16.8+, Vue 3, Angular (standalone), Svelte, or none (vanilla JS)
• Runtime: Despia Native SDK with window.bundleNumber available

License

MIT