playx_core 2.0.0
playx_core: ^2.0.0 copied to clipboard
Core package for playx eco system contains shared classes and utilities.
PlayX Core #
The core of the PlayX ecosystem: one package for the building blocks most Flutter apps need, with a consistent, null-safe, easy-to-test API.
Features #
| Preferences | PlayxPrefs, PlayxAsyncPrefs and PlayxPrefsWithCache: typed key-value storage, plus maps, lists and objects as JSON. |
| Secure preferences | PlayxSecurePrefs: encrypted storage with a choice of backends (flutter_secure_storage, simple_secure_storage, AES-encrypted preferences), an auto mode that falls back when a plugin fails, hidden key names, and WebCrypto on web. |
| Environment configuration | PlayxEnv: .env files, per-environment and per-flavor files, --dart-define values, typed getters, required keys. |
| Secure env | Keep API keys and other sensitive values out of plain sight: a command encrypts them into your app, with CI/CD support. |
| Extensions | Helpers for String, Iterable, DateTime, Duration, Color, Locale, BuildContext, padding, borders and radius. |
| Utilities | Safe type conversion and JSON access, MapUtils (optionally in isolates), system UI, clipboard, platform checks, WebUtils. |
| Logging | PlayxLogger: named loggers, levels and pluggable backends. |
| Dependency injection | GetIt is re-exported and ready after PlayxCore.bootCore. |
Installation #
Requires Dart 3.12+ and Flutter 3.44+.
dependencies:
playx_core: ^2.0.0
import 'package:playx_core/playx_core.dart';
Coming from 1.x? Read the migration guide.
Quick start #
Boot the core once, before runApp:
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await PlayxCore.bootCore(
// Optional: load configuration from .env files (see below).
envSettings: const PlayxEnvSettings(requiredKeys: ['API_URL']),
);
runApp(const MyApp());
}
bootCore creates the stores you ask for through settings objects (prefsSettings, securePrefsSettings, envSettings, workerManagerSettings). See Getting started.
Preferences #
await PlayxPrefs.setString('name', 'Jane');
final name = PlayxPrefs.getString('name'); // synchronous read
final age = PlayxPrefs.getInt('age', fallback: 18);
await PlayxPrefs.setObject('user', user, toJson: (u) => u.toJson());
final saved = PlayxPrefs.maybeGetObject('user', fromJson: User.fromJson);
Three stores share one API: PlayxPrefs (synchronous reads), PlayxAsyncPrefs (always the latest platform value) and PlayxPrefsWithCache. Learn more.
Secure preferences #
await PlayxSecurePrefs.setString('access_token', token);
final token = await PlayxSecurePrefs.getString('access_token');
Choose where the data lives, and let auto fall back when a plugin fails on a device:
await PlayxCore.bootCore(
securePrefsSettings: const PlayxSecurePrefsSettings(
storageType: PlayxSecureStorageType.auto,
encryptKeys: true, // also hide key names such as "access_token"
),
);
Learn more, including switching an existing app.
Environment configuration #
# .env # .env.prod
API_URL=https://api.example.com API_URL=https://api.prod.example.com
TIMEOUT=30s
# pubspec.yaml
flutter:
assets: [.env, .env.prod]
final apiUrl = PlayxEnv.getUri('API_URL', fallback: Uri());
final timeout = PlayxEnv.getDuration('TIMEOUT', fallback: const Duration(seconds: 30));
final debug = PlayxEnv.getBool('DEBUG');
flutter run --dart-define=PLAYX_ENV=prod # loads .env, then .env.prod
flutter run --dart-define=PLAYX_DEFINES="DEBUG=true" # overrides at build time
Values from the base file, the environment (or --flavor) file and build-time defines are merged, later sources winning. Learn more.
Secure env #
Put sensitive values in a gitignored .env.secrets and encrypt them into your app:
dart run playx:secure_env --env prod # or: dart run playx_core:secure_env
import 'generated/playx_secure_env.g.dart';
await PlayxCore.bootCore(
envSettings: const PlayxEnvSettings(secureEnv: playxSecureEnv),
);
PlayxEnv.getString('STRIPE_KEY'); // decrypted in memory; hidden from PlayxEnv.all
Works in CI/CD too (Codemagic, GitHub Actions, Vercel). Anything an app can decrypt on its own can be extracted by a determined attacker, so read what it does and doesn't protect.
Extensions and utilities #
'jane doe'.capitalizedInitialChar; // 'J'
[1, 2, 3, 4, 5].chunked(2); // [[1, 2], [3, 4], [5]]
DateTime.now().startOfWeek();
Container(padding: 16.p, decoration: BoxDecoration(borderRadius: 12.borderRadius));
GridView.count(crossAxisCount: context.crossAxisCount(), children: items);
final age = asIntOr(json, 'user.age', fallback: 0); // safe nested JSON access
See Extensions and Utilities.
Documentation #
Read it online at playx-flutter.github.io/playx_core, with search and the API reference, or browse the guides here:
| Guide | |
|---|---|
| Getting started | Requirements, bootCore, GetIt, disposing |
| Preferences | The three stores, typed getters, maps, lists and objects |
| Secure preferences | Backends, auto, key names, web, migration, failures |
| Environment configuration | Files, environments, flavors, defines, getters |
| Secure env | The secure_env command, CI/CD, threat model |
| Extensions | Every extension, by type |
| Utilities | Conversion, JSON, MapUtils, system UI, WebUtils |
| Logging | PlayxLogger |
| Testing | Testing your code, and this package |
| Migrating to 2.0 | Breaking changes, with before/after code |
| CI/CD samples | Codemagic, GitHub Actions, Vercel |
The API reference covers every class and member, and the changelog lists what changed in each version.
Example #
The example app is a runnable project using preferences and environment configuration with environments, build-time defines and secure env.
Support and contribution #
For questions, issues, or feature requests, please visit the GitHub repository. Contributions are welcome!
dart format . # CI checks formatting with a pinned Flutter version
flutter analyze lib test
flutter test # unit tests
flutter test --coverage # with coverage
See also #
- Playx: The PlayX ecosystem for redundant features, reduced code, and improved productivity.
- Playx_theme: Multi-theme features for Flutter apps.
- Playx_localization: Localization and internationalization for Flutter apps.
License #
This project is licensed under the MIT License - see the LICENSE file for details.