Solid Framework for Flutter

A read is tracked if the widget subtree containing it must rebuild when the signal changes. A read is untracked if it reads the current value but must NOT cause the enclosing widget subtree to subscribe.

Untracked reads still have .value appended by the rewriter for type safety, but they do not trigger SignalBuilder wrapping of their parent widget subtree.

Queries annotated with @SolidQuery are lazy and materialize upon their first invocation.

Auto-tracking: If one @SolidQuery reads the value of another @SolidQuery within its body, Solid automatically establishes a reactive dependency. The downstream query will automatically refresh whenever the upstream query emits a new value.

Safe Access: To avoid errors when an upstream query fails, use the asReady?.value pattern. This prevents the common mistake of calling .value on a query that is currently in an error state, which would otherwise rethrow the error.

Opting out: If you need to read a query value without establishing a reactive dependency, use the .untracked extension: <queryName>().untracked.

When a query re-executes because a dependency changed, it defaults to a "refreshing" mode rather than entering the loading state. This prevents the UI from flickering or showing a full-screen loading indicator while new data is being fetched.

Detecting a refresh

Use the .isRefreshing property to check if a query is currently updating its data:

fetchData().isRefreshing

Changing refresh behavior

If you want the query to enter the loading state again (showing the loading widget) every time it re-executes, set useRefreshing to false in the annotation:

@SolidQuery(useRefreshing: false)

In a Solid project, the standard Flutter directory structure is inverted.

Never edit files in lib/.

In Solid, lib/ contains the generated output from build_runner. Every time you run the generator, it overwrites lib/ based on the contents of source/. Any manual changes made to lib/ will be silently lost on the next build.

• Source of truth: source/<x>.dart
• Generated output: lib/<x>.dart
• Entry point: source/main.dart (not lib/main.dart)

Solid operates as a transpiler rather than a simple code generator. It takes code written in the source directory and transforms it into working code located in the lib directory. This is necessary because Flutter requires the app to be built from the lib folder.

Note: The mapping from ^source/{{}}.dart to lib/{{}}.dart is hard-coded in the solid_generator builder configuration. Changing these directories requires forking the builder config in packages/solid_generator/build.yaml.

In Solid, every reference to a reactive identifier is categorized as either a read or a write. Understanding this distinction is critical for managing reactivity and avoiding unnecessary rebuilds.

• Writes: Any assignment form (=, compound assignments like +=, ++, --). Writes do not subscribe to the signal. The rewriter automatically appends .value to ensure typechecking, but writes never trigger SignalBuilder wrapping.
• Reads: Observing a reactive value (e.g., Text(counter), if (counter > 0), print(counter)). Reads may or may not subscribe to the signal depending on the context (see Tracked vs Untracked Reads).

Starlight projects follow a specific directory structure for content and assets:

• Documentation Content: Place .md or .mdx files in src/content/docs/. Each file name determines its route.
• Images: Store images in src/assets/ and reference them in Markdown using relative links.
• Static Assets: Place files like favicons in the public/ directory.
• Configuration: Project settings are managed via astro.config.mjs and content.config.ts.

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   └── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

Solid uses an inverted directory structure compared to standard Flutter development:

• source/ folder: This is your source of truth. This is where you write your authored code and annotations.
• lib/ folder: This is the generated realm. Solid transpiles your code from source/ into an optimized version in lib/.

Important: Never edit the lib/ folder manually, as it is overwritten by the generator. All imports within the same package should be relative to avoid resolving to the generated lib/ files instead of your authored files.

The @SolidEnvironment() annotation is used to inject a value from the widget tree into a widget. It functions similarly to SwiftUI's @Environment property wrapper: it is type-keyed, and the lookup occurs lazily on the first access.

Crucially, if the injected type contains @SolidState fields, those fields remain reactive within your build method. This allows for fine-grained reactivity where only the specific widgets reading the state rebuild, rather than the entire widget tree.

class CounterDisplay extends StatelessWidget {
  CounterDisplay({super.key});

  @SolidEnvironment()
  late Counter counter;

  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Counter is ${counter.value}'));
  }
}

The @SolidState annotation cannot be used on getters within a class that already extends State<X>. This is because the generator does not yet support adding @SolidState logic to an existing State subclass. If you need reactive state, define it in a separate controller or use a StatefulWidget pattern that doesn't involve annotating getters inside the State class itself.

// This will cause a CodeGenerationError
class _ProbeAWidgetState extends State<ProbeAWidget> {
  @SolidState() int counter = 0;
  @SolidState() int get probe => counter * 2; // Error: @SolidState getter on existing State<X> subclass is not yet supported
}