When to use Nomos Flutter
Nomos Flutter brings the power of the Nomos Peer Office—a typed runtime contract platform originally built for JavaScriptCore and WebAssembly—directly into your Flutter applications. By exposing a native bridge to the shared Peer Office, the package lets developers define, validate, and synchronize complex form data across iOS, Android, web, and desktop with a single, type‑safe API. The underlying engine runs JavaScriptCore on Apple platforms and a lightweight WASM runtime on all other targets, ensuring consistent behavior regardless of the host environment. This makes Nomos Flutter an ideal choice for enterprises that need deterministic validation logic, offline‑first capabilities, and real‑time peer collaboration without rewriting business rules for each platform.
When to use Nomos Flutter? If your project already relies on Nomos contracts for server‑side validation or you need a single source of truth for form schemas that can be shared between web, mobile, and embedded devices, this package eliminates duplication and reduces the risk of mismatched validation rules. It shines in scenarios such as regulatory‑heavy data entry, multi‑step onboarding flows, or any application where form definitions evolve frequently and must be propagated instantly to all clients. By keeping the validation logic in the Nomos runtime, you avoid the pitfalls of maintaining parallel Dart and JavaScript validation code, and you gain the ability to push updates to the contract without redeploying the entire app.
From an architectural perspective, Nomos Flutter fits neatly into a clean‑architecture or layered approach. The package acts as a data‑validation layer that sits between your UI widgets and your domain/repository layer. You can feed a Nomos schema into a `NomosForm` widget, let the runtime handle field‑level validation, and then retrieve a strongly‑typed result that can be sent to any backend—whether it’s a REST API, GraphQL endpoint, or a Nomos Peer Office server. Because the runtime is deterministic, unit tests can be written against the same contract used in production, giving you confidence that validation behaves identically on every platform.
Getting started is straightforward. After adding the dependency with `flutter pub add nomos_flutter`, you initialise the Peer Office with your compiled contract bundle. The package abstracts the platform‑specific details, automatically selecting JavaScriptCore on iOS/macOS and a WASM interpreter on Android, web, and desktop. Once initialised, you can create a `NomosForm` by passing a JSON schema or a pre‑compiled Nomos module. The widget renders standard Flutter form fields, but all validation is performed by the Nomos engine, guaranteeing that the same rules are applied on the server side. For production use, remember to bundle the contract files securely, enable code‑signing on iOS, and test the WASM fallback on low‑end devices to ensure acceptable performance.
Beginners will appreciate the declarative API: define your form schema once, drop a `NomosForm` into the widget tree, and listen to the `onSubmit` callback for a validated data object. Advanced users can tap into the lower‑level `NomosRuntime` to execute custom contract functions, perform peer‑to‑peer synchronization, or integrate with existing state‑management solutions like Provider or Riverpod. The package also offers a debugging console that mirrors the Nomos REPL, making it easy to inspect contract state during development. Whether you are building a simple contact form or a complex multi‑user workflow, Nomos Flutter provides a reliable, type‑safe bridge between your Flutter UI and the powerful Nomos validation engine.
Pros
- single source of truth for validation
- consistent behavior across all platforms
- offline support via WASM
- real‑time peer synchronization
- type‑safe Dart API
Watch outs
- adds a runtime dependency (JSCore/WASM)
- initial learning curve for Nomos contracts
- larger asset bundle size
Setup notes
1. Add the dependency: `flutter pub add nomos_flutter` 2. Run `flutter pub get` to fetch the package. 3. Place your compiled Nomos contract (e.g., `nomos_contract.wasm` or `nomos_contract.js`) in the `assets/` folder and declare it in `pubspec.yaml`. 4. Initialise the runtime early, typically in `main()`: ```dart await NomosFlutter.initialize( contractAssetPath: 'assets/nomos_contract.wasm', ); runApp(MyApp()); ``` 5. Use `NomosForm` widgets to render forms based on the contract schema. 6. For production, enable asset compression and verify the integrity of the contract bundle.
Requires Flutter 3.0 or newer and Dart 2.17+. Supports iOS, Android, web, macOS, Windows, and Linux. Uses JavaScriptCore on Apple platforms and a WASM interpreter on all others. Ensure that the target platform allows execution of WASM modules (most modern browsers and Flutter desktop builds do).
```dart
import 'package:flutter/material.dart';
import 'package:nomos_flutter/nomos_flutter.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await NomosFlutter.initialize(
contractAssetPath: 'assets/nomos_contract.wasm',
);
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(title: const Text('Nomos Form Demo')),
body: const Padding(
padding: EdgeInsets.all(16),
child: NomosForm(
schemaId: 'user_registration',
onSubmit: (validatedData) {
// validatedData is a strongly‑typed map matching the contract
debugPrint('Form submitted: $validatedData');
},
),
),
),
);
}
}
```