Code Generation Overview

XWidget Builder generates Dart code from your specification files. It produces five outputs: inflaters, icons, controllers, a registry that exposes a single registration entry point for XWidget.initialize(), and an XML schema for IDE code completion.

Running the Generator

xc generate

Or without the global command:

dart run xwidget_builder:generate

Options

Option	Abbr	Description	Default
`--only`		Components to generate (comma-separated)	`inflaters,icons,controllers`
`--schema-docs`	`-s`	Schema documentation format (`cdata` or `html`). Overrides `schema.documentationFormat`.	—
`--allow-deprecated`	`-d`	Include deprecated constructors and arguments	`false`
`--no-logo`		Suppress the XWidget logo	—
`--no-title`		Suppress the title banner	—

Selective Generation

Use --only to generate a subset of the per-component outputs:

# Generate only inflaters
xc generate --only inflaters

# Generate inflaters and icons only
xc generate --only inflaters,icons

Allowed values: inflaters, icons, controllers.

Note

The registry always regenerates, regardless of --only, because it reflects the current state of the other generated files. The schema regenerates only when inflaters are built — schema generation is part of the inflater builder. Running --only inflaters therefore writes all three: inflaters.g.dart, .xwidget/fragments_schema.g.xsd, and registry.g.dart.

Schema Documentation Format

Dart doc comments on Flutter widgets are embedded in the generated XSD so IDEs can show them as tooltips. Different IDEs have different preferences:

cdata (default) — wraps converted HTML in a CDATA section. Works broadly but renders as raw HTML tags in IntelliJ-based IDEs.
html — emits proper HTML elements that IntelliJ-based IDEs render as formatted tooltips.

You can set this permanently in xwidget_config.yaml under schema.documentationFormat, or override for a single run:

xc generate --schema-docs html

Generated Outputs

Component	Default Output Path	Details
Inflaters	`lib/xwidget/generated/inflaters.g.dart`	Inflaters
Icons	`lib/xwidget/generated/icons.g.dart`	Icons
Controllers	`lib/xwidget/generated/controllers.g.dart`	Controllers
Registry	`lib/xwidget/generated/registry.g.dart`	Registry
Schemas	`.xwidget/fragments_schema.g.xsd`, `routes_schema.g.xsd`, `values_schema.g.xsd`, `schema_catalog.g.xml`	Schema

All output paths are configurable via xwidget_config.yaml (the registry's under the registry.target key). The registry is always generated — --only does not skip it.

Registering Generated Code

In your app's main(), pass the generated registerXWidgetComponents to XWidget.initialize:

import 'package:xwidget/xwidget.dart';
import 'xwidget/generated/registry.g.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await XWidget.initialize(register: registerXWidgetComponents);

  runApp(MyApp());
}

The registry calls the three per-component registration functions and populates XWidget.config with the paths from your xwidget_config.yaml. You don't need to import inflaters.g.dart, icons.g.dart, or controllers.g.dart directly — the registry does it for you.

See Registry for what the generated registry contains and why it exists.

Configuration

The generator reads xwidget_config.yaml from the .xwidget/ config directory (pre-0.7.0 projects have it at the project root; the first builder command moves it). This file extends XWidget's built-in defaults, so most projects need only a minimal config.

See Configuration for the full reference.