Skip to main content

playx_core 2.0.0 copy "playx_core: ^2.0.0" to clipboard
playx_core: ^2.0.0 copied to clipboard

Core package for playx eco system contains shared classes and utilities.

PlayX Core #

pub package
Build codecov
License: MIT

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.