Skip to main content

changelog_flutter_kit 1.1.1 copy "changelog_flutter_kit: ^1.1.1" to clipboard
changelog_flutter_kit: ^1.1.1 copied to clipboard

Published 18 days ago
SDKFlutter
PlatformAndroidiOSLinuxmacOSWindows
→

Metadata

A headless and platform-adaptive 'What's New' and release notes kit for Flutter apps with native iOS Cupertino, Material 3, SemVer comparison, and persistence.

More...

Changelog Kit

Pub Version Pub Points Pub Likes License: MIT Platform Vibe Coded

changelog_flutter_kit

A fluent, platform-adaptive, and headless release notes & changelog kit for Flutter apps.
Showcase your awesome new app features natively on iOS (Cupertino HIG) and Android (Material 3) with zero friction.

Whether you want a drop-in, platform-adaptive modal that looks and feels like Apple's official system onboarding sheet on iOS and Material 3 on Android, or full headless control to render custom announcement banners and cards, changelog_flutter_kit gives you the best of both worlds.

💡 Zero-Config Storage: changelog_flutter_kit automatically defaults to SharedPreferences (SharedPrefsWhatsNewStorage). Seen versions, update states, and history are tracked across app launches right out of the box—no database configuration required!

📑 Table of Contents #

✨ Features #

  • 🎨 Platform-Adaptive UI:
    • iOS & macOS: Apple Human Interface Guidelines Cupertino modal sheet, SF-style typography, squircle icon badges, pull-down drag handle, and CupertinoButton.filled.
    • Android: Material 3 bottom sheet modal with tonal surface elevation, pill badges, and FilledButton.
    • Desktop, Web & Tablets: Centered modal popup dialog (WhatsNewPresentationStyle.dialog).
  • ⚡ Smart Version Lifecycle:
    • Fresh Installs: Silently marks the current version as seen so new users aren't greeted with a backlog of old release notes.
    • Same Version: Returns immediately with zero UI interruption.
    • Upgraded Version: Automatically displays the announcement modal for newly installed versions.
  • 🌐 Dynamic & Remote Loading (OTA):
    • Fetch release notes on the fly from an HTTP/HTTPS CDN or backend API without submitting App Store updates.
    • Transparent offline fallback to a bundled local asset file.
  • 👑 Monetization & Pro Hooks:
    • Gated entries display lock badges and dimmed opacity for free users.
    • Interactive onProTap callbacks allow instant routing to your paywall or subscription screen.
  • 🧩 100% Headless Engine:
    • Decoupled WhatsNewController, WhatsNewBuilder, and WhatsNewGate enable custom in-app notification cards, snackbars, or bespoke sheets.
  • 🏷️ SemVer 2.0.0 Precision:
    • Full precedence support for semantic versions, pre-release tags (2.0.0-beta.1), build numbers (+42), and v prefixes (v1.2.0).
  • 🌍 Multi-Language Localization (i18n):
    • Built-in UI presets for English, Spanish, French, German, and Arabic (with RTL support).
    • Automatically matches device locale for changelog titles and descriptions.
  • 📜 Full Version History:
    • Built-in multi-version scrollable view for your app's Settings or "About" screen (WhatsNew.showHistory or ChangelogKit.showHistory).

🏆 Why changelog_flutter_kit? #

Feature changelog_flutter_kit Basic Dialogs / Other Packages
Apple HIG Cupertino Sheet (Native SF typography & squircles) ❌ (Generic alert dialog)
Material 3 Bottom Sheet (M3 tonal elevation & pill badges) ❌
Zero-Config Persistence (Automatic SharedPreferences backing) ❌ (Manual prefs code required)
SemVer 2.0.0 Spec Parsing (Handles pre-releases, build tags & v prefix) ❌ (Naive string comparison)
Over-the-Air (OTA) Remote CDN (Live updates with offline asset fallback) ❌ (Hardcoded only)
Pro Feature Monetization Gating (Lock badges, dimmed opacity, paywall tap hooks) ❌
100% Headless Mode (WhatsNewBuilder & WhatsNewGate) ❌ (Coupled directly to UI)
Multi-Language (i18n) (Presets + dynamic per-entry locale matching) ❌ (English only)
Dedicated Version History View (WhatsNew.showHistory for Settings menu) ❌

🔄 How Version Tracking Works #

changelog_flutter_kit manages the entire update detection lifecycle automatically:

                                      ┌────────────────────────┐
                                      │   App Starts Up /      │
                                      │   checkAndShow()       │
                                      └───────────┬────────────┘
                                                  │
                                                  ▼
                                      ┌────────────────────────┐
                                      │  Query Storage for     │
                                      │  Last Seen Version     │
                                      └───────────┬────────────┘
                                                  │
                 ┌────────────────────────────────┼────────────────────────────────┐
                 │                                │                                │
                 ▼                                ▼                                ▼
       [First Ever Install]              [Same Version Run]               [App Has Updated]
        No prior version seen             Current == LastSeen              Current > LastSeen
                 │                                │                                │
                 ▼                                ▼                                ▼
      ┌────────────────────┐            ┌────────────────────┐           ┌────────────────────┐
      │ Silently record    │            │ Return immediately │           │ Present Adaptive   │
      │ current version    │            │ (No UI displayed)  │           │ "What's New" Sheet │
      │ (No popup shown)   │            └────────────────────┘           └─────────┬──────────┘
      └────────────────────┘                                                       │
                                                                                   ▼
                                                                         ┌────────────────────┐
                                                                         │ User taps "Got it" │
                                                                         │ -> Version marked  │
                                                                         │    as seen         │
                                                                         └────────────────────┘

📦 Installation #

Add changelog_flutter_kit to your Flutter project:

flutter pub add changelog_flutter_kit

Import it in your Dart code:

import 'package:changelog_flutter_kit/changelog_flutter_kit.dart';

🚀 Quick Start #

1. Define Changelogs #

You can define your changelog directly in Dart code or load it from JSON:

import 'package:flutter/material.dart';
import 'package:changelog_flutter_kit/changelog_flutter_kit.dart';

const myChangelogs = [
  VersionChangelog(
    version: '2.1.0',
    title: 'Performance & Polish',
    releaseDate: 'October 2026',
    entries: [
      ChangelogEntry(
        type: ChangeType.feature,
        title: 'Adaptive iOS & Android UI',
        text: 'Sheets automatically adapt to Apple Human Interface Guidelines and Material 3.',
        iconOverride: Icons.auto_awesome,
      ),
      ChangelogEntry(
        type: ChangeType.pro,
        title: 'Cloud Realtime Sync',
        text: 'Keep your preferences synchronized across all your devices.',
        isPro: true, // Dimmed with lock badge for free users
        iconOverride: Icons.cloud_sync_rounded,
      ),
      ChangelogEntry(
        type: ChangeType.improvement,
        title: 'Faster Startup',
        text: 'App launch time reduced by 40% with optimized caching.',
        iconOverride: Icons.speed_rounded,
      ),
      ChangelogEntry(
        type: ChangeType.fix,
        title: 'Dark Theme Contrast',
        text: 'Resolved status bar contrast issue on OLED displays.',
        iconOverride: Icons.bug_report_rounded,
      ),
    ],
  ),
];

2. Auto-Show on App Launch #

Call ChangelogKit.checkAndShow (or WhatsNew.checkAndShow) inside your home screen's initState or top-level shell:

@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addPostFrameCallback((_) {
    // Automatically uses SharedPreferences to persist seen state!
    ChangelogKit.checkAndShow(
      context,
      changelogs: myChangelogs,
      isProUser: currentUser.isSubscribed,
      onProTap: (entry) => Navigator.pushNamed(context, '/paywall'),
    );
  });
}

3. Full Version History Screen #

Allow users to browse all past release notes anytime from your Settings or "About" screen with a single line:

ListTile(
  leading: const Icon(Icons.history_rounded),
  title: const Text("What's New"),
  subtitle: const Text('View release history and past updates'),
  onTap: () {
    ChangelogKit.showHistory(
      context,
      changelogs: myChangelogs,
      isProUser: currentUser.isSubscribed,
      onProTap: (entry) => Navigator.pushNamed(context, '/paywall'),
    );
  },
)

🎨 Platform-Adaptive UI Modes #

changelog_flutter_kit supports multiple presentation modes via WhatsNewPresentationStyle:

ChangelogKit.checkAndShow(
  context,
  changelogs: myChangelogs,
  presentationStyle: WhatsNewPresentationStyle.auto, // Default
);

Cupertino (Apple HIG on iOS & macOS) #

  • Apple Human Interface Guidelines modal presentation with drag indicator.
  • San Francisco typography hierarchy.
  • Squircle icon container badges with iOS system styling.
  • CupertinoButton.filled primary action button.

Material 3 (Android & Web) #

  • Material 3 bottom sheet modal with tonal elevation.
  • Dynamic color scheme integration (Theme.of(context).colorScheme).
  • Pill badge chips and FilledButton.

Centered Dialog (Desktop & Tablets) #

  • Constrained centered modal popup (WhatsNewPresentationStyle.dialog).
  • Optimized for larger viewports, mouse pointer interactions, and desktop platforms (Windows, macOS, Linux, Web).

🌐 Dynamic Loading (Remote CDN & Local Assets) #

Avoid submitting App Store reviews just to fix a typo or publish updated release notes. Load your changelogs from a remote CDN endpoint or local JSON asset file with automatic offline fallback.

1. Over-The-Air (OTA) from a Remote CDN #

ChangelogKit.checkAndShowFromNetwork(
  context,
  url: Uri.parse('https://api.myawesomeapp.com/v1/changelogs.json'),
  fallbackAsset: 'assets/changelogs.json', // Loaded automatically if device is offline
  isProUser: currentUser.isSubscribed,
  onProTap: (entry) => Navigator.pushNamed(context, '/paywall'),
);

2. From a Bundled Asset #

ChangelogKit.checkAndShowFromAsset(
  context,
  assetPath: 'assets/changelogs.json',
);

3. JSON Schema Specification #

Create your changelog file as either a JSON array or an object with a "changelogs" key:

[
  {
    "version": "2.1.0",
    "title": "Performance & Polish",
    "releaseDate": "October 2026",
    "localizedTitles": {
      "es": "Rendimiento y mejoras",
      "fr": "Performance et finition"
    },
    "entries": [
      {
        "type": "feature",
        "title": "Adaptive UI",
        "text": "Native look and feel on iOS and Android.",
        "iconOverride": "auto_awesome",
        "translations": {
          "es": {
            "title": "Interfaz adaptativa",
            "text": "Apariencia nativa en iOS y Android."
          }
        }
      },
      {
        "type": "pro",
        "title": "Cloud Realtime Sync",
        "text": "Sync data effortlessly across devices.",
        "isPro": true
      },
      {
        "type": "fix",
        "title": "Dark Mode Contrast",
        "text": "Fixed status bar visibility issue on OLED screens."
      }
    ]
  }
]

👑 Monetization & Pro Feature Gating #

Drive app subscriptions and paywall conversions directly from your release announcements:

  1. Flag premium entries with isPro: true on ChangelogEntry.
  2. Pass isProUser: currentUser.isSubscribed to checkAndShow or WhatsNewSheet.
  3. Provide an onProTap callback:
ChangelogKit.checkAndShow(
  context,
  changelogs: myChangelogs,
  isProUser: currentUser.isSubscribed,
  onProTap: (entry) {
    // Direct users to your paywall or upgrade screen
    Navigator.pushNamed(context, '/paywall', arguments: entry);
  },
);

When isProUser is false, Pro items are rendered with:

  • Reduced opacity (configurable via WhatsNewThemeData.dimmedProOpacity).
  • A lock indicator icon.
  • Direct tap-to-unlock gesture invoking onProTap.

🧩 Headless Mode (100% Custom UI) #

If you prefer building custom announcement cards, banners, snackbars, or bespoke dialogs, changelog_flutter_kit provides a clean headless architecture.

1. WhatsNewBuilder (Reactive Custom UI) #

WhatsNewBuilder queries the state controller and passes a WhatsNewState object to your builder function:

WhatsNewBuilder(
  controller: WhatsNewController(changelogs: myChangelogs),
  builder: (context, state) {
    if (state.isLoading) return const SizedBox.shrink();
    if (!state.hasUpdate) return const SizedBox.shrink();

    final changelog = state.currentChangelog!;
    return Card(
      margin: const EdgeInsets.all(16),
      color: Colors.indigo.shade50,
      child: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          mainAxisSize: MainAxisSize.min,
          children: [
            Row(
              children: [
                const Icon(Icons.celebration, color: Colors.indigo),
                const SizedBox(width: 8),
                Text(
                  "What's New in v${changelog.version}!",
                  style: const TextStyle(fontWeight: FontWeight.bold, fontSize: 16),
                ),
              ],
            ),
            const SizedBox(height: 8),
            ...changelog.entries.map((e) => Text('• ${e.text}')),
            const SizedBox(height: 12),
            FilledButton(
              onPressed: state.markCurrentSeen,
              child: const Text('Dismiss'),
            ),
          ],
        ),
      ),
    );
  },
)

2. WhatsNewGate (Declarative Lifecycle Gate) #

Use WhatsNewGate to wrap a screen and execute a callback once when an update is available:

WhatsNewGate(
  controller: WhatsNewController(changelogs: myChangelogs),
  onUpdateAvailable: (context, changelog, markSeen) {
    showDialog(
      context: context,
      builder: (ctx) => AlertDialog(
        title: Text("Welcome to v${changelog.version}"),
        content: Text(changelog.entries.first.text),
        actions: [
          TextButton(
            onPressed: () {
              markSeen();
              Navigator.pop(ctx);
            },
            child: const Text('Awesome!'),
          ),
        ],
      ),
    );
  },
  child: const HomeScreen(),
)

🎨 Theming & Custom Slot Builders #

Customize colors, typography, layout, and inject custom widgets into presentation slots via WhatsNewThemeData:

ChangelogKit.checkAndShow(
  context,
  changelogs: myChangelogs,
  presentationStyle: WhatsNewPresentationStyle.auto,
  theme: WhatsNewThemeData(
    primaryColor: Colors.deepPurple,
    backgroundColor: Colors.white,
    showDragHandle: true,
    dimmedProOpacity: 0.4,
    
    // Custom header slot
    headerBuilder: (context, changelog) {
      return Padding(
        padding: const EdgeInsets.all(16),
        child: Text(
          '🎉 Welcome to ${changelog.version}',
          style: Theme.of(context).textTheme.headlineSmall,
        ),
      );
    },

    // Custom entry tile slot
    entryTileBuilder: (context, entry, isProUser, onProTap) {
      return ListTile(
        title: Text(entry.title ?? entry.text),
        subtitle: entry.title != null ? Text(entry.text) : null,
      );
    },

    // Custom action button slot
    actionBuilder: (context, onDismiss, label) {
      return FilledButton.icon(
        onPressed: onDismiss,
        icon: const Icon(Icons.check_circle_outline),
        label: Text(label),
      );
    },
  ),
);

🌍 Localization & Multi-Language (i18n) #

1. Built-In UI Presets #

changelog_flutter_kit includes ready-to-use localized chrome strings for common languages:

ChangelogKit.checkAndShow(
  context,
  changelogs: myChangelogs,
  localization: WhatsNewLocalization.spanish, // .french, .german, .arabic
);

2. Integration with AppLocalizations #

Integrate directly with Flutter's standard AppLocalizations (.arb files) or easy_localization:

final l10n = AppLocalizations.of(context)!;

ChangelogKit.checkAndShow(
  context,
  changelogs: myChangelogs,
  localization: WhatsNewLocalization(
    gotIt: l10n.gotItButton,
    versionHistory: l10n.releaseNotesTitle,
    titleTemplate: (version) => l10n.whatsNewVersion(version),
    typeLabels: {
      ChangeType.feature: l10n.tagNew,
      ChangeType.improvement: l10n.tagImproved,
      ChangeType.fix: l10n.tagFix,
      ChangeType.pro: l10n.tagPro,
    },
  ),
);

3. Dynamic Multilingual Changelog Content #

Both Dart models and JSON payloads support entry-level translations. When rendering, changelog_flutter_kit inspects Localizations.maybeLocaleOf(context) and automatically presents the translated title and description matching the user's language.

💾 Pluggable Persistence #

By default, changelog_flutter_kit uses SharedPrefsWhatsNewStorage, providing persistence across app restarts without writing any storage code.

Custom Database Integration #

Need to store seen states in Hive, Drift, Isar, SQLite, or Firebase/Supabase? Implement WhatsNewStorage:

class MyCustomStorage implements WhatsNewStorage {
  @override
  Future<String?> getLastSeenVersion() async => /* read from DB */;

  @override
  Future<void> setLastSeenVersion(String version) async => /* write to DB */;

  @override
  Future<Set<String>> getAllSeenVersions() async => /* query DB */;

  @override
  Future<void> addSeenVersion(String version) async => /* append to DB */;

  @override
  Future<void> clear() async => /* clear DB keys */;
}

Supply your custom storage engine to the controller or facade:

ChangelogKit.initialize(
  changelogs: myChangelogs,
  storage: MyCustomStorage(),
);

Unit Testing Storage #

For unit tests and ephemeral runs, use the built-in InMemoryWhatsNewStorage:

final testStorage = InMemoryWhatsNewStorage(initialLastSeen: '1.0.0');

ChangelogKit.checkAndShow(
  context,
  changelogs: myChangelogs,
  storage: testStorage,
);

🏷️ Change Types & Badge Reference #

changelog_flutter_kit provides 7 semantic change types with purpose-crafted badge styles and icons:

ChangeType Default Label Default Icon Color Accent Typical Usage
feature ★ NEW Icons.star_rounded Blue (#2196F3) Brand new user-facing functionality
improvement ⚡ IMPROVED Icons.bolt_rounded Purple (#9C27B0) Performance or UX enhancement
fix 🔧 FIX Icons.build_rounded Orange (#FF9800) Bug fix or stability improvement
pro 👑 PRO Icons.workspace_premium Amber (#FFB300) Pro or subscription exclusive feature
security 🔒 SECURITY Icons.security_rounded Green (#4CAF50) Security hardening or privacy update
deprecated ⏱ DEPRECATED Icons.history_toggle_off Slate (#78909C) Upcoming deprecation notice
breaking ⚠️ BREAKING Icons.warning_amber Red (#E53935) Breaking API or behavior change

📚 API Reference Summary #

Class / Method Description
ChangelogKit.checkAndShow(...) Checks storage and presents the adaptive sheet if a new version is detected.
ChangelogKit.checkAndShowFromNetwork(...) Fetches JSON release notes over OTA CDN and presents sheet if updated.
ChangelogKit.checkAndShowFromAsset(...) Loads bundled JSON changelog and presents sheet if updated.
ChangelogKit.showHistory(...) Displays full multi-version scrollable history screen.
WhatsNew Full facade class (equivalent alias to ChangelogKit).
WhatsNewBuilder Reactive headless widget exposing WhatsNewState for custom banners/cards.
WhatsNewGate Declarative widget executing a callback once when an update is available.
WhatsNewController Pure Dart state controller handling version comparison and storage persistence.
WhatsNewThemeData Complete styling configuration (colors, padding, slot builders).
WhatsNewLocalization Localization strings and language presets (spanish, french, german, arabic).
WhatsNewStorage Persistence contract (SharedPrefsWhatsNewStorage, InMemoryWhatsNewStorage).

🧪 Testing & Debugging #

During development, you may want to test the update sheet repeatedly without changing version numbers:

// Reset seen versions in SharedPreferences during debug sessions:
final storage = SharedPrefsWhatsNewStorage();
await storage.clear();

// Or use InMemoryWhatsNewStorage for widget tests:
testWidgets('Shows update sheet when new version arrives', (tester) async {
  final storage = InMemoryWhatsNewStorage(initialLastSeen: '1.0.0');
  // ... test assertions
});

📱 Example Showcase App #

The repository includes a comprehensive, interactive example application demonstrating all presentation styles, headless widgets, remote loading, paywall hooks, and a simulated version switcher.

To run the example:

git clone https://github.com/andronasef/changelog_flutter_kit.git
cd changelog_flutter_kit/example
flutter run

📄 License #

This package is licensed under the MIT License.

← Metadata

2
likes
160
points
417
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Metadata

A headless and platform-adaptive 'What's New' and release notes kit for Flutter apps with native iOS Cupertino, Material 3, SemVer comparison, and persistence.

Repository (GitHub)
View/report issues

Topics

#changelog #release-notes #whats-new #bottom-sheet #cupertino

License

MIT (license)

Dependencies

flutter, package_info_plus, shared_preferences

More

Packages that depend on changelog_flutter_kit

Back