Quick Start

This guide will help you get up and running with XWidget in just a few minutes. For the full local-to-cloud walkthrough, continue with Guided Setup. For a broader description of the components and features, see Features and the Concepts section.

Prerequisites:

• Flutter: >=3.35.0
• Dart SDK: >=3.9.0 <4.0.0

1. Install XWidget

Install XWidget and XWidget Builder with the following command. XWidget provides the core functionality, while XWidget Builder includes development tools for code generation, project initialization, and the cloud/analytics CLI.

flutter pub add xwidget dev:xwidget_builder

2. Initialize Project

New Project

If you are starting a new project, use the --new-app flag to replace the current project with the example app. This provides a solid starting point for building your XWidget application.

dart run xwidget_builder:init --new-app

Existing Project

If you have an existing project, omit the --new-app flag to safely add XWidget without replacing your current code.

dart run xwidget_builder:init

Tip

You can install the global xc command for a shorter syntax. Once installed, the commands above become xc init --new-app and xc init. See CLI Setup for installation instructions.

3. Register Schema

The generated schemas (in .xwidget/) give you validation, code completion, and tooltip documentation when editing fragments, values, and routes files. The IDE plugins register them automatically.

The IDE plugins register the schema automatically.

4. Add More Components

To register additional components, modify lib/xwidget/inflater_spec.dart and run:

dart run xwidget_builder:generate --only inflaters

Or with the xc command:

xc generate --only inflaters

See Inflaters for details on writing inflater specs.

5. Cloud Setup

To enable over-the-air UI updates and analytics, switch to CloudResources in your main():

import 'package:xwidget/xwidget.dart';

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

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

  await XWidget.initialize(
    register: registerXWidgetComponents,
    resources: CloudResources(
      projectKey: '<your-project-key>',
      storageKey: '<your-storage-key>',
      channel: 'production',
      version: '1.0.0',
    ),
  );

  runApp(MyApp());
}

See CloudResources for the full setup guide and Cloud Overview for deploying your first bundle.

If you want analytics without a cloud-hosted UI, use LocalResources.withAnalytics. See LocalResources.

6. IDE Plugins

Install the XWidget plugin for your IDE for EL syntax highlighting, fragment and controller navigation, hot reload, and component generation:

Next Steps

• Fragments — Learn how to define UIs in XML
• Controllers — Add business logic and state management
• Expression Language — Write dynamic expressions in your markup
• Code Generation — Configure what gets generated