Solid

Solid (Flutter)

Solid is a tiny framework on top of Flutter. You write reactive state directly on a StatelessWidget in source/; the solid_generator build_runner builder transpiles each source/<x>.dart into lib/<x>.dart, turning your class into a StatefulWidget with Signal/Computed/Effect/Resource plumbing from flutter_solidart. Inspired by SwiftUI (@Environment) and SolidJS (fine-grained reactivity).

User-facing docs: https://solid.mariuti.com.

Step 0 — Is this project Solid?

Before doing anything, decide if the project actually uses Solid. The user may not say "Solid" anywhere — and an existing lib/ directory plus solid_annotations/solid_generator not being in pubspec means this is not a Solid project.

Run this check first:

grep -E '^\s*(solid_annotations|solid_generator):' pubspec.yaml

• Match found → this is a Solid project. Follow this skill.
• No match → not a Solid project. Don't apply Solid conventions. Skip this skill.

The same check via Read tool works too: read pubspec.yaml and look for either package name under dependencies: or dev_dependencies:. A Solid setup typically has solid_annotations (runtime) under dependencies and solid_generator plus build_runner under dev_dependencies.

Cardinal rule

Edit source/<x>.dart. Never edit lib/<x>.dart.

In Flutter, lib/ is where you write code. In Solid, lib/ is generated output — every time build_runner runs, it overwrites lib/<x>.dart from source/<x>.dart. Hand-edits to lib/ are lost on the next build. The user-facing entry point is source/main.dart; lib/main.dart is generated.

This inverts Flutter muscle memory. The rest of the Flutter ecosystem (flutter run, pub packages, IDE templates, every tutorial on the internet) assumes lib/ is the source of truth. In this project it isn't. Apply the substitution everywhere.

Decision shortcuts

Third-party packages: substitute source/ for lib/

When the user (or another AI) installs a new pub package, the package's README, examples, and any AI-generated setup instructions will all assume lib/ is the source of truth. In a Solid project that assumption is wrong.

Rule of thumb: the package itself stays in pubspec.yaml as the docs describe. Only the files you write that import it move from lib/ to source/. Examples:

• go_router README says "create lib/router.dart" → create source/router.dart instead, and import it from source/main.dart via a relative path.
• freezed says "create lib/models/user.dart" → create source/models/user.dart. Freezed's own *.freezed.dart generated output still lands wherever build.yaml puts it (typically next to the source file under lib/, since freezed reads from lib/); but in a Solid project you want freezed to read from source/ too. Add source/** to freezed's build.yaml sources list (Solid's setup already does this — keep it).
• riverpod generator says "create lib/providers/..." → create source/providers/....
• drift says "create lib/database.dart" → create source/database.dart.

For the full list and per-package gotchas, read references/third-party-packages.md.

The key thing to tell yourself: "the docs say lib/. In this project, that means source/."

Same-package imports must be relative

Inside a source/ file, reference other source files via relative paths (../controllers/foo.dart), never via package:<self>/foo.dart. The package: form resolves to lib/ (the generated realm), pointing your source file at lowered Signal types — the generator now rejects it at build time. Cross-package imports (flutter, solid_annotations, provider, third-party) keep the package: form as usual.

Annotation cheat sheet

Each annotation goes on a class member of a StatelessWidget (or any class — @SolidEnvironment also works in State<X>). The generator turns the widget into a StatefulWidget under the hood.

• @SolidState() — reactive state. Docs: https://solid.mariuti.com/guides/state.

  • Valid on: instance field with initializer, late non-nullable instance field, nullable instance field, instance getter (derived state).
  • Invalid: final, const, static, setter, method, top-level.
  • Example: @SolidState() int counter = 0; or @SolidState() int get doubleCounter => counter * 2;.

• @SolidEffect() — side effect that re-runs whenever its tracked dependencies change. Docs: https://solid.mariuti.com/guides/effect.

  • Valid on: instance method returning void.
  • Example: @SolidEffect() void logCounter() { print('Counter: $counter'); }.

• @SolidQuery() — reactive async/stream resource. Docs: https://solid.mariuti.com/guides/query.

  • Valid on: instance method returning Future<T> or Stream<T>. No parameters.
  • Call site fetchData() returns a Resource<T> exposing .when(ready:, loading:, error:), .maybeWhen(...), .isRefreshing, .refresh().
  • Options: debounce: Duration(...), useRefreshing: false.
  • Read @SolidState fields from the body to make the query react to them.

• @SolidEnvironment() — inject a value from the widget tree (SwiftUI-style). Docs: https://solid.mariuti.com/guides/environment.

  • Valid on: late field on a StatelessWidget or State<X>.
  • Bound on first access to the nearest ancestor Provider<T>.
  • Provide via .environment<T>() extension shipped by solid_annotations, or Provider<T> from package:provider.

For full target rules per annotation, read references/annotation-contract.md. For canonical idioms, read references/patterns.md.