example/README.md

restage_codegen example #

restage_codegen is the build-time code generator behind the Restage SDK. You don't call it directly. You add it as a dev dependency and run build_runner. It reads a plain Flutter widget annotated with its surface type and compiles it into the small, inert Remote Flutter Widget (.rfw) render blob the Restage runtime renders. The same pipeline serves every surface: onboarding screens, in-app messages, surveys, paywalls, and any full screen you author.

1. Add the toolchain #

# pubspec.yaml
dependencies:
  restage: ^2.0.0          # runtime SDK + the surface annotations

dev_dependencies:
  build_runner: ^2.4.0
  restage_codegen: ^2.0.0  # the build-time compiler (this package)

2. Author a surface in plain Flutter #

A surface is a plain widget annotated with its surface type. This example is an independently published message screen. Use @Paywall for a specialized paywall, @Screen() for a reusable flow screen, or @FlowGraph(surface: Surface.<category>) for a typed flow. The source uses your own widgets and your app's theme; there are no shim classes to learn.

import 'package:flutter/material.dart';
import 'package:restage/restage.dart';

part 'restage.generated/welcome.restage.g.dart';

@Screen(id: 'welcome', surface: Surface.message)
final class WelcomeScreen extends StatelessWidget {
  const WelcomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Text('Welcome', style: Theme.of(context).textTheme.headlineMedium),
        const SizedBox(height: 8),
        const Text('Server-driven UI that renders as real Flutter widgets.'),
      ],
    );
  }
}

3. Compile it #

dart run build_runner build

restage_codegen runs as a build_runner builder (wired through build.yaml): it analyzes the annotated source, decomposes structured Flutter types (text styles, paddings, gradients, borders) against the widget catalog, and writes a small .rfw blob as generated output. Commit the generated output your app bundles: it carries only inert references and literal values.

What it produces #

• A per-surface .rfw render blob the Restage runtime decodes into real Flutter widgets, in your own widget tree.
• A generated SurfaceScreenRef<E> and publication entry in lib/generated/restage.publication.json.
• Catalog entries for any custom widgets you registered with @RestageWidget (see rfw_catalog_compiler).

Push the generated entry by id, then publish the pushed revision:

restage surface push welcome
restage surface publish welcome

The manifest is the publication authority.

The runtime half of the loop, rendering the blob in your app, lives in the restage package. A complete, runnable gallery is in apps/examples.

Migration from legacy source annotations #

Older source may use @ScreenSource, @PaywallSource, or @FlowSource. Those spellings are deprecated compatibility frontends. New source should use @Screen, @Paywall, and @FlowGraph(surface: ...).