Vyuh CDX

Appearance

Installation ​

Get started with the Vyuh Entity System in your Flutter application.

Requirements

  • Dart SDK 3.9 or higher
  • Flutter 3.32 or higher (latest stable recommended)
  • A Vyuh Framework project with vyuh_core configured

Authenticate with pub.vyuh.tech first

The Entity System packages is hosted on the private pub.vyuh.tech registry. Before running pub get, register a Bearer token issued by Vyuh Technologies based on your plan.

Run the one-time setup:

dart pub token add https://pub.vyuh.tech

Don't have a token yet? Email ask@vyuh.tech to request one. For full details (CI, Docker, rotation, troubleshooting), see the Pub Token Setup guide.

Add Dependencies

Add vyuh_entity_system, vyuh_entity_system_ui, vyuh_entity_annotations and vyuh_entity_generator  to your pubspec.yaml as hosted dependencies:

pubspec.yaml

Then resolve dependencies:

Run the code generator to materialize the *.g.dart files:

Setup

The entity system ships as five focused packages. For a Flutter app, you typically pull in two runtime packages and the annotations + generator pair:

  • vyuh_entity_system — widget-free runtime: models, API, services, authorization, plugin system.
  • vyuh_entity_system_ui — Flutter widgets, layouts, editors, route builders, command palette wiring. Re-exports vyuh_entity_system.
  • vyuh_entity_annotations — pure-Dart @Entity / @Field / @ServerEntity annotations and the Authorize DSL.
  • vyuh_entity_generator — build_runner builder that turns the annotations into *.entity.dart and *.server.dart part files.

Annotations & code generation

The fastest path is annotations + generator. Skip them only if you really want to hand-write every FieldDefinition, API client, and configuration — see the Packages page for both flavours.

1. Create the Entity System Plugin ​

The EntitySystemPlugin is the central entry point. Register it with your Vyuh application:

dart
import 'package:vyuh_entity_system/vyuh_entity_system.dart';

final entityPlugin = EntitySystemPlugin(
  baseUrl: 'https://api.example.com',
  // OpenAuthorizationProvider grants every Authorize check — perfect for
  // local development. Swap in a real AuthorizationProvider for production.
  authorizationProvider: OpenAuthorizationProvider(),
);

2. Register with Vyuh Platform ​

Add the plugin to your Vyuh platform initialization:

dart
import 'package:vyuh_core/vyuh_core.dart';
import 'package:vyuh_entity_system/vyuh_entity_system.dart';

vyuh.runApp(
  plugins: PluginDescriptor(
    content: DefaultContentPlugin(...),
    others: [entityPlugin],
  ),
  features: () => [
    myFeature,
  ],
);

3. Register Entities via Feature Descriptor ​

Entities are registered through EntityExtensionDescriptor inside a feature:

dart
import 'package:vyuh_core/vyuh_core.dart';
import 'package:vyuh_entity_system/vyuh_entity_system.dart';

final lmsFeature = FeatureDescriptor(
  name: 'lms',
  title: 'Learning Management System',
  extensions: [
    EntityExtensionDescriptor(
      entities: [
        courseConfig,
        participantConfig,
        trainerConfig,
      ],
    ),
  ],
);

Each EntityConfiguration is registered with the plugin during feature initialization. The plugin automatically generates GoRouter routes for every entity whose metadata has route visibility. MenuVisibility also implies a route because menu entries must be navigable.

Verify the Setup

After setup, your entities should appear in the application's navigation menu (when their EntityMetadata.visibility includes MenuVisibility) and their routes should be accessible.

You can verify registration programmatically:

dart
// Access the entity system plugin
final plugin = vyuh.entity;

// Look up the typed configuration for a specific entity
final courseConfig = plugin?.getConfig<Course>();

// List the registered entity identifiers
final identifiers = plugin?.registeredIdentifiers;

// Use the canonical route builder — never hardcode entity URLs
final route = plugin?.getConfig<Course>()?.route;
context.go(route!.list());          // /lms/courses
context.go(route.view('course-1')); // /lms/courses/course-1

analysis_options.yaml

Add **/*.entity.dart to the analyzer.exclude list when you use the generator. The generated files emit deliberately permissive types and you do not want them flagged in CI.

yaml
analyzer:
  exclude:
    - "**/*.g.dart"
    - "**/*.entity.dart"

Next Steps ​