When to use Gg One Core
The **Gg One Core** package is the foundational layer for the gg_one family of tools, providing a lightweight yet powerful kernel that handles state caching, command abstraction, verification steps, and gg-publish.json management. By centralising these concerns, the package lets developers focus on business logic while keeping configuration and runtime state predictable and testable. It works seamlessly with any Flutter architecture, from simple widget‑centric apps to complex clean‑architecture or MVVM projects, and can be adopted incrementally without a full rewrite.
When building medium to large‑scale Flutter applications, managing transient and persisted state across multiple screens, background services, and CI pipelines quickly becomes a source of bugs. Gg One Core introduces a typed cache that stores immutable snapshots of your app's state, enabling fast roll‑backs, deterministic debugging, and smoother hot‑reload experiences. The cache is built on top of Dart's `ValueNotifier` and can be persisted to local storage or remote back‑ends with minimal boilerplate. This makes it ideal for scenarios where you need to remember user preferences, form progress, or feature‑flag toggles across app launches.
Beyond state, the package supplies a **command base** that standardises how you define, execute, and verify actions throughout your codebase. Each command encapsulates a single responsibility, returns a typed result, and can be wrapped in verification steps such as input validation, permission checks, or network availability. This pattern reduces duplicated error handling and makes unit testing straightforward – you simply mock the command and assert the expected outcome. The verification pipeline is fully configurable, allowing you to enable or disable checks based on build flavour or runtime conditions.
A unique aspect of Gg One Core is its handling of the `gg-publish.json` manifest. This file drives the publishing workflow for the entire gg_one suite, describing versioning, dependency constraints, and custom scripts. The package reads, validates, and updates this manifest at build time, ensuring that your CI/CD pipeline always works with a consistent configuration. By integrating this step into your Flutter build process, you eliminate manual errors and keep your release process auditable.
**Setup and production considerations** are straightforward. The package has no native dependencies, so it works on all Flutter platforms – iOS, Android, web, macOS, Windows, and Linux. However, because the cache can be persisted to the file system, you should configure appropriate storage permissions for mobile platforms and consider encryption for sensitive data. In production, enable the built‑in verification steps to guard against malformed commands and stale state, and use the provided `ggPublish` helper to automate version bumps during CI runs. For beginners, start with the simple `CacheProvider` example, then progressively adopt the command infrastructure as your app grows.
Overall, Gg One Core offers a disciplined approach to state and command management while keeping the integration surface minimal. Whether you are building a personal project that needs reliable caching or a corporate app with strict publishing pipelines, the package gives you a reusable kernel that scales with your needs.
Pros
- lightweight pure‑dart implementation
- unified command and verification API
- built‑in cache persistence
- automatic gg‑publish.json handling
- platform‑agnostic
Watch outs
- niche focus on gg_one tool suite
- additional learning curve for command pattern
- no built‑in UI widgets
Setup notes
Add the package to your project with the following command: ``` flutter pub add gg_one_core ``` Then import the core utilities: ```dart import 'package:gg_one_core/gg_one_core.dart'; ``` Initialize the cache early in `main()` and configure the gg‑publish.json path if you use custom CI scripts.
Requires Flutter 3.10 or higher and Dart SDK >=2.19. The package is pure Dart, so it works on all Flutter-supported platforms (mobile, web, desktop). No additional native setup is needed.
```dart
import 'package:flutter/material.dart';
import 'package:gg_one_core/gg_one_core.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await CacheProvider.initialize(); // sets up in‑memory and persistent cache
runApp(const MyApp());
}
class IncrementCommand extends Command<int> {
final int value;
IncrementCommand(this.value);
@override
Future<int> execute() async {
// Simple verification step
if (value < 0) throw ArgumentError('value must be non‑negative');
return value + 1;
}
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(title: const Text('Gg One Core Demo')),
body: Center(
child: ElevatedButton(
onPressed: () async {
final result = await IncrementCommand(5).run();
CacheProvider.instance.save('lastResult', result);
debugPrint('Result saved: $result');
},
child: const Text('Run Command'),
),
),
),
);
}
}
```