Skip to content

Configuration Reference

xwidget_config.yaml

The code generator reads xwidget_config.yaml from the .xwidget/ config directory. Projects created before builder 0.7.0 have it at the project root — the first builder command you run moves it into .xwidget/ automatically. The file extends XWidget's built-in defaults (defined in package:xwidget_builder/res/default_config.yaml), so most projects need only a minimal config.

A typical configuration:

fragmentsPath: "resources/fragments"
valuesPath: "resources/values"

inflaters:
  imports: [
    "dart:ui",
    "package:flutter/foundation.dart",
    "package:flutter/gestures.dart",
  ]
  sources: [ "lib/xwidget/inflater_spec.dart" ]
  includes: [ "lib/xwidget/inflater_spec_includes.dart" ]

icons:
  sources: [ "lib/xwidget/icon_spec.dart" ]

There are two top-level path settings and five top-level component mappings.

Resource Paths

# Where fragment XML files live, relative to the project root.
# DEFAULT: "resources/fragments"
fragmentsPath:

# Where value XML files (strings, colors, etc.) live, relative to the project root.
# DEFAULT: "resources/values"
valuesPath:

These values are baked into the generated registry.g.dart as XWidget.config defaults. LocalResources and CloudResources read them at load time when their own path parameters are not provided.

Registry

registry:
  # Where the generated registry is written.
  # DEFAULT: "lib/xwidget/generated/registry.g.dart"
  target:

The registry is always generated (--only does not skip it); target only controls where it's written.

Inflaters

inflaters:
  # Output path for generated inflater code.
  # DEFAULT: "lib/xwidget/generated/inflaters.g.dart"
  target:

  # Additional imports to include in the generated output. Appended to
  # XWidget's default import list.
  # DEFAULT: [ "package:xwidget/xwidget.dart" ]
  imports: [ ]

  # Inflater specification source files.
  # DEFAULT: none
  sources: [ ]

  # Files whose contents (excluding imports) are copied verbatim into the
  # generated output.
  # DEFAULT: none
  includes: [ ]

  # Constructor arguments to exclude from XML.
  # Format: "ClassName:argumentName" or "*:argumentName"
  # DEFAULT: See 'package:xwidget_builder/res/default_config.yaml'
  constructor_exclusions: [ ]

  # Override default values for constructor arguments.
  # Format: "ClassName:argumentName": "value"
  # DEFAULT: See 'package:xwidget_builder/res/default_config.yaml'
  constructor_arg_defaults:

  # Define how string values are parsed into Dart types.
  # Lookup priority: ClassName:argName > *:argName > ArgumentType
  # DEFAULT: See 'package:xwidget_builder/res/default_config.yaml'
  constructor_arg_parsers:

See Inflaters for detailed usage.

Schema

schema:
  # Controls how Dart doc comments (from widget/inflater source code) get
  # embedded in the generated fragments_schema.g.xsd file for IDE tooltip display.
  # Valid values: "cdata" or "html"
  # DEFAULT: "cdata"
  #   cdata: wraps the raw markdown-converted HTML in a CDATA section in the XSD.
  #          Works in some IDEs but not others.
  #   html:  emits proper HTML that renders nicely in IntelliJ-based IDEs
  #          (Android Studio, IntelliJ IDEA).
  documentationFormat: "cdata"

  # XSD template file providing the schema skeleton.
  # DEFAULT: "xwidget_builder|res/schema_template.xsd"
  template:

  # Map Dart types to XSD simple types for attribute validation.
  # DEFAULT: See 'package:xwidget_builder/res/default_config.yaml'
  types:
    "bool": "boolAttributeType"
    "Alignment": "AlignmentAttributeType"

  # Attributes to omit from the schema.
  # Format: "ClassName:attrName" or "*:attrName"
  # DEFAULT: See 'package:xwidget_builder/res/default_config.yaml'
  attribute_exclusions: [ ]

See Schema for detailed usage.

Controllers

controllers:
  # Output path for generated controller registration code.
  # DEFAULT: "lib/xwidget/generated/controllers.g.dart"
  target:

  # Additional imports.
  # DEFAULT: [ "package:xwidget/xwidget.dart" ]
  imports: [ ]

  # Glob patterns for controller source files.
  # DEFAULT: [ "lib/xwidget/controllers/**.dart" ]
  sources: [ ]

See Controllers for detailed usage.

Icons

icons:
  # Output path for generated icon registration code.
  # DEFAULT: "lib/xwidget/generated/icons.g.dart"
  target:

  # Additional imports.
  # DEFAULT: [ "package:xwidget/xwidget.dart" ]
  imports: [ ]

  # Icon specification source files.
  # DEFAULT: none
  sources: [ ]

See Icons for detailed usage.

xwidget_cloud.yaml

This file is generated automatically by xc cloud deploy on first deployment. It links your local project directory to its XWidget Cloud counterpart.

project_id: 5Tv_2OaW_2v8DPrlIKxzg

project_id — the cloud project identifier. Used by xc cloud and xc analytics commands to resolve the project without prompting.

This file should be committed to version control so that all team members can run cloud and analytics commands from the project directory.