Skip to content

khflutterlib

khflutterlib is KodeHauz's shared Flutter foundation. It's a monorepo of packages that apps pull in as git dependencies, all pinned to one release tag. The current release is khflutterlib-v0.4.3.

New here? Start with the hackathon quick start to add the packages to your own app, or copy the starter app for an app that already has everything wired up.

Packages

Five packages ship today. Add only the ones you need, and pin every one to the same release tag (see Release train).

kh_core: the foundation

kh_core is pure Dart, with no Flutter dependency, and every other package builds on it. It defines how errors travel through an app. Data sources throw a KhException, and repositories turn it into a KhFailure inside a KhResult<T>, a sealed success-or-failure type you fold or switch over. Typed remote failures (KhNetworkFailure, KhUnauthorizedFailure, KhServerFailure, and so on) come with khFailureFromStatusCode to map an HTTP status to the right failure. It also has KhEnvironmentConfig for per-environment settings, the KhEntity/KhPage base models, the KhReadRepository/KhMutableRepository contracts, string/date/iterable extensions, and the KhDebouncer and KhRetry helpers.

kh_theme: design system

kh_theme turns one seed color (or an exact ColorScheme) into complete light and dark ThemeData with KhTheme.light()/KhTheme.dark(). It holds the design tokens (KhSpacing, KhRadius, KhElevation, KhSizes, KhTypography in the bundled Inter font), semantic success/warning/info colors through KhThemeExtension, and per-component corner radii (KhShapeTokens) and brand gradients (KhGradients).

kh_ui: widgets

kh_ui is the widget library. Each widget wraps a standard Material widget and takes its look from the theme. It includes KhButton (with sizes, pill shape and a loading state), text and search fields, dropdowns, date pickers, checkboxes, radios, switches, cards, dialogs, bottom sheets, snackbars, chips and badges, avatars, skeleton loaders, two navigation shells (KhBottomNav, KhNavDrawer), and loading/empty/error states. KhErrorState turns a KhFailure into user-safe copy.

kh_screens: ready-made screens

kh_screens puts kh_ui widgets together into full screens: KhSplashScreen, KhOnboardingFlow and KhLoginForm. None of them assume a router or state-management library. Each one reports back through a callback, and your app decides where to go next.

kh_utils: helpers

kh_utils is pure Dart. It has KhValidators, which plug straight into any form field's validator, KhFormatters for dates, relative times, currency, numbers and phone numbers, KhPhoneRegion for country-aware phone validation and E.164 normalization, and KhLogger, a leveled logger that hides debug and info output when your KhEnvironmentConfig has logging turned off.

Overall architecture

Internal dependencies (each arrow points at what a package imports):

kh_screens ──► kh_ui, kh_theme, kh_core        Flutter
kh_ui      ──► kh_theme, kh_core               Flutter
kh_theme   ──► (no kh_* dependencies)          Flutter
kh_utils   ──► kh_core                         pure Dart
kh_core    ──► (no kh_* dependencies)          pure Dart
  • Layered, no cycles. Dependencies only point down the stack. kh_core and kh_utils never import Flutter, so they work in plain Dart code and tests.
  • Theme-driven. Widgets read their defaults from Theme.of(context), not from token constants, so a custom seed color, font or shape preset passed to KhTheme reaches every widget. Every widget also takes a per-instance override (style, color, and so on).
  • Results, not exceptions, across layers. Repositories return KhResult<T>. The UI renders failures with KhErrorState, which never shows a failure's raw developer message.
  • No router or state-management lock-in. Screens and flows finish through callbacks, so they work with Navigator, go_router, Riverpod, Bloc or anything else.
  • Shipped as one release train. Every package is consumed from the same khflutterlib-v<x.y.z> git tag. See Release train.

Where to go next

  • Hackathon quick start: the dependency block, the one easy-to-miss pubspec.yaml setting, and a minimal app.
  • Getting started: working inside this repo (bootstrap, gallery, tests, goldens), plus the full consumer setup.
  • Example gallery: run every widget live.