NgxVersionView

A powerful Angular library that enables version-aware component rendering for seamless feature management based on application versions. Perfect for progressive feature rollouts, maintaining backward compatibility, and A/B testing.

Features

• 🚀 Version-Aware Components - Render different components based on your application's version
• 🧠 Smart Feature Selection - Automatically selects the most appropriate component for the current version
• ⚙️ Multiple Version Strategies - Support for semantic versioning (1.1.0) and date-based versioning
• 🎯 Declarative API - Simple decorator-based approach for clear and maintainable code
• 💉 Dependency Injection Integration - Fully compatible with Angular's DI system
• 🔄 Dynamic Component Loading - Efficiently load and render the right component at runtime
• 🔍 Transparent Caching - Optimized performance through internal caching mechanisms
• 📦 Standalone Component Support - Fully compatible with Angular's standalone components

Installation

npm install ngx-version-view --save

Quick Start

1. Set up the Version Provider

First, provide the version management service with your app's version:

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideVersionView, VersionStrategyType } from 'ngx-version-view';
import { BehaviorSubject } from 'rxjs';

// Create a version stream - in a real app, this might come from an API
const versionStream = new BehaviorSubject<string>('1.0.0');

export const appConfig: ApplicationConfig = {
  providers: [
    // ... other providers
    provideVersionView({
      type: VersionStrategyType.SEMANTIC, // or VersionStrategyType.DATE
      version: versionStream,
    }),
  ],
};

For simpler cases, you can use the shorthand version:

provideVersionViewSimple(versionStream, true); // true = use semantic versioning

2. Create Version-Specific Components

Create components for different versions and decorate them with version metadata:

// basic-feature.component.ts
import { Component, Input } from '@angular/core';
import { VersionFeature } from 'ngx-version-view';

@Component({
  selector: 'app-basic-feature',
  standalone: true,
  template: `<div class="basic">Basic Feature UI - v1.0</div>`,
})
@VersionFeature({
  key: 'userDashboard',
  minVersion: '1.0.0',
  maxVersion: '2.0.0',
})
export class BasicFeatureComponent {
  @Input() userId: string = '';
}

// advanced-feature.component.ts
import { Component, Input } from '@angular/core';
import { VersionFeature } from 'ngx-version-view';

@Component({
  selector: 'app-advanced-feature',
  standalone: true,
  template: `<div class="advanced">Advanced Feature UI - v2.0+</div>`,
})
@VersionFeature({
  key: 'userDashboard',
  minVersion: '2.0.0',
})
export class AdvancedFeatureComponent {
  @Input() userId: string = '';
}

3. Register the Components

Register your version-specific components with the service:

// app.component.ts
import { Component, OnInit } from '@angular/core';
import { ViewService } from 'ngx-version-view';
import { BasicFeatureComponent } from './basic-feature.component';
import { AdvancedFeatureComponent } from './advanced-feature.component';

@Component({
  // ...
})
export class AppComponent implements OnInit {
  constructor(private viewService: ViewService) {}

  ngOnInit() {
    // Register features manually (alternative to using decorators)
    this.viewService.registerFeatures([
      {
        key: 'userDashboard',
        minVersion: '1.0.0',
        maxVersion: '2.0.0',
        component: BasicFeatureComponent,
      },
      {
        key: 'userDashboard',
        minVersion: '2.0.0',
        component: AdvancedFeatureComponent,
      },
    ]);
  }
}

4. Use the Component in Templates

<ngx-view-component
  key="userDashboard"
  [data]="{ userId: currentUser.id }"
>
  <!-- Fallback content if no matching version is found -->
  <p>This feature is not available in your current version</p>
</ngx-view-component>

Advanced Usage

Date-Based Versioning

For applications that use dates as version numbers:

import { provideVersionView, VersionStrategyType, DateFormat } from 'ngx-version-view';
import { BehaviorSubject } from 'rxjs';

const versionStream = new BehaviorSubject<string>('2023-10-15');

provideVersionView({
  type: VersionStrategyType.DATE,
  dateFormat: DateFormat.YYYY_MM_DD_DASH, // Or other supported formats
  version: versionStream,
});

Available Date Formats

The library supports multiple date formats:

export enum DateFormat {
  DD_MM_YYYY_DOT = 'dd.MM.yyyy', // 15.10.2023
  MM_DD_YYYY_DOT = 'MM.dd.yyyy', // 10.15.2023
  YYYY_MM_DD_DOT = 'yyyy.MM.dd', // 2023.10.15
  YYYY_MM_DD_DASH = 'yyyy-MM-dd', // 2023-10-15
  MM_DD_YYYY_DASH = 'MM-dd-yyyy', // 10-15-2023
  DD_MM_YYYY_DASH = 'dd-MM-yyyy', // 15-10-2023
}

Programmatic Feature Selection

You can also get components programmatically:

import { Component, OnInit } from '@angular/core';
import { ViewService } from 'ngx-version-view';

@Component({
  selector: 'app-dynamic-wrapper',
  template: `
    <ng-container *ngComponentOutlet="featureComponent; inputs: inputData"></ng-container>
  `,
})
export class DynamicWrapperComponent implements OnInit {
  featureComponent: any;
  inputData = { userId: 'user-123' };

  constructor(private viewService: ViewService) {}

  ngOnInit() {
    this.featureComponent = this.viewService.getFeatureComponent('userDashboard');
  }
}

Current Version Access

Access the current application version anywhere in your app:

import { Component } from '@angular/core';
import { ViewService } from 'ngx-version-view';

@Component({
  selector: 'app-version-display',
  template: `<div>Running on version: {{ currentVersion() }}</div>`,
})
export class VersionDisplayComponent {
  currentVersion = this.viewService.currentVersion;

  constructor(private viewService: ViewService) {}
}

Dynamic Version Updates

You can dynamically update the application version:

import { Component } from '@angular/core';
import { BehaviorSubject } from 'rxjs';

@Component({
  // ...
})
export class AdminComponent {
  constructor(@Inject(VERSION_STREAM) private versionStream: BehaviorSubject<string>) {}

  updateAppVersion(newVersion: string) {
    this.versionStream.next(newVersion);
    // All version-aware components will automatically update
  }
}

API Reference

Core Components

Component	Description
VersionFeatureComponent	The component that renders version-appropriate UI based on feature key

Services

Service	Description
ViewService	Core service for registering and retrieving version-based components

Decorators

Decorator	Description
@VersionFeature()	Marks a component with version metadata

Configuration

Function	Description
provideVersionView()	Configures the library with full options
provideVersionViewSimple()	Simplified configuration function

Models and Interfaces

Interface	Description
VersionConfig	Configuration options for version strategies
FeatureConfig	Configuration for a version-specific feature
VersionFeatureOptions	Options for the @VersionFeature decorator
VersionStrategy	Interface for implementing custom version comparison strategies

Version Strategies

Strategy	Description
SemanticVersionStrategy	Handles semantic versioning (e.g., 1.2.3)
DateVersionStrategy	Handles date-based versioning with configurable formats

Examples

Progressive Feature Rollout

@VersionFeature({
  key: 'paymentMethod',
  minVersion: '1.0.0',
  maxVersion: '1.5.0',
})
export class BasicPaymentComponent {}

@VersionFeature({
  key: 'paymentMethod',
  minVersion: '1.5.0',
  maxVersion: '2.0.0',
})
export class EnhancedPaymentComponent {}

@VersionFeature({
  key: 'paymentMethod',
  minVersion: '2.0.0',
})
export class AdvancedPaymentComponent {}

Feature Flags

// Enable a feature only in specific versions
@VersionFeature({
  key: 'experimentalFeature',
  minVersion: '1.5.0',
  maxVersion: '1.6.0', // Only available in this version range as a test
})
export class ExperimentalFeatureComponent {}

A/B Testing

// Variant A (for 50% of version 2.x users)
@VersionFeature({
  key: 'checkoutFlow',
  minVersion: '2.0.0',
  maxVersion: '3.0.0',
})
export class CheckoutVariantAComponent {}

// Variant B (for 50% of version 2.x users)
@VersionFeature({
  key: 'checkoutFlow',
  minVersion: '2.0.0',
  maxVersion: '3.0.0',
})
export class CheckoutVariantBComponent {}

// In your service that manages which variant to show
constructor(private viewService: ViewService) {
  const variant = Math.random() > 0.5 ? CheckoutVariantAComponent : CheckoutVariantBComponent;

  this.viewService.registerFeature({
    key: 'checkoutFlow',
    minVersion: '2.0.0',
    maxVersion: '3.0.0',
    component: variant
  });
}

Best Practices

1. Organize by Feature Keys: Use consistent feature keys across your application
2. Version Boundaries: Define clear min/max version boundaries
3. Fallback Content: Always provide fallback content in the ngx-view-component
4. Testing: Test each version-specific component independently
5. Documentation: Document version compatibility for each feature

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

About the Author

Kiet Le - zenkiet