|
4 | 4 | link: '/documentation/watch_it/your_first_watch_functions' |
5 | 5 | --- |
6 | 6 |
|
7 | | -<div class="header-with-logo"> |
8 | | - <div class="header-content"> |
9 | | - |
10 | | -# Getting Started with watch_it |
11 | | - |
12 | | - </div> |
13 | | - <img src="/images/watch_it.svg" alt="watch_it logo" width="100" class="header-logo" /> |
| 7 | +<div style="display: flex; align-items: center; gap: 1rem; margin-bottom: 2rem;"> |
| 8 | + <img src="/images/watch_it.svg" alt="watch_it logo" width="100" /> |
| 9 | + <h1 style="margin: 0;">Getting Started</h1> |
14 | 10 | </div> |
15 | 11 |
|
16 | | -:::warning 🚧 WORK IN PROGRESS |
17 | | -This documentation is currently being reviewed and updated. Content may change based on feedback. |
18 | | -::: |
| 12 | +<strong>watch_it</strong> makes your Flutter widgets automatically rebuild when data changes. No <code>setState</code>, no <code>StreamBuilder</code>, just simple reactive programming built on top of get_it. |
| 13 | + |
| 14 | +<strong>Key benefits:</strong> |
| 15 | +<ul style="list-style: none; padding-left: 0;"> |
| 16 | + <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/your_first_watch_functions.md">Automatic rebuilds</a></strong> - Widgets rebuild when data changes, no <code>setState</code> needed</li> |
| 17 | + <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/how_it_works.md">No manual listeners</a></strong> - Automatic subscription & cleanup, prevent memory leaks</li> |
| 18 | + <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/watching_streams_and_futures.md">Simpler async</a></strong> - Replace <code>StreamBuilder</code>/<code>FutureBuilder</code> with <code>watchStream()</code>/<code>watchFuture()</code></li> |
| 19 | + <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/handlers.md">Side effects</a></strong> - Navigation, dialogs, toasts without rebuilding</li> |
| 20 | + <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/lifecycle.md">Lifecycle helpers</a></strong> - <code>callOnce()</code> for initialization, <code>createOnce()</code> for controllers</li> |
| 21 | + <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/observing_commands.md">Command integration</a></strong> - Observe <code>command_it</code> commands reactively</li> |
| 22 | +</ul> |
19 | 23 |
|
20 | | -watch_it makes your Flutter widgets automatically rebuild when data changes. No `setState`, no `StreamBuilder`, just simple reactive programming. |
| 24 | +<strong>Common use cases:</strong> |
| 25 | +- Build reactive UIs that automatically update when data changes |
| 26 | +- Replace <code>setState</code>, <code>StreamBuilder</code>, and <code>FutureBuilder</code> with simple watch functions |
| 27 | +- Handle side effects (navigation, dialogs) without rebuilding widgets |
| 28 | +- Observe command execution state (loading, errors, results) |
21 | 29 |
|
22 | 30 | > Join our support Discord server: [https://discord.gg/ZHYHYCM38h](https://discord.gg/ZHYHYCM38h) |
23 | 31 |
|
| 32 | +--- |
| 33 | + |
24 | 34 | ## Installation |
25 | 35 |
|
26 | | -Add to your `pubspec.yaml`: |
| 36 | +Add watch_it to your `pubspec.yaml`: |
27 | 37 |
|
28 | 38 | ```yaml |
29 | 39 | dependencies: |
30 | 40 | watch_it: ^2.0.0 |
31 | 41 | get_it: ^8.0.0 # watch_it builds on get_it |
32 | 42 | ``` |
33 | 43 |
|
34 | | -## Why watch_it? (Compared to get_it alone) |
35 | | -
|
36 | | -get_it gives you dependency injection. watch_it adds **reactive UI** on top: |
37 | | -
|
38 | | -<ul style="list-style: none; padding-left: 0;"> |
39 | | - <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/your_first_watch_functions.md">Automatic rebuilds</a></strong> - Widgets rebuild when data changes, no <code>setState</code> needed</li> |
40 | | - <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/how_it_works.md">No manual listeners</a></strong> - Automatic subscription & cleanup, prevent memory leaks</li> |
41 | | - <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/watching_streams_and_futures.md">Simpler async</a></strong> - Replace <code>StreamBuilder</code>/<code>FutureBuilder</code> with <code>watchStream()</code>/<code>watchFuture()</code></li> |
42 | | - <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/handlers.md">Side effects</a></strong> - Navigation, dialogs, toasts without rebuilding</li> |
43 | | - <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/lifecycle.md">Lifecycle helpers</a></strong> - <code>callOnce()</code> for initialization, <code>createOnce()</code> for controllers</li> |
44 | | - <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ <strong><a href="/documentation/watch_it/observing_commands.md">Command integration</a></strong> - Observe <code>command_it</code> commands reactively</li> |
45 | | -</ul> |
46 | | -
|
47 | | -**Bottom line:** get_it manages dependencies, watch_it makes them **reactive** in your UI. |
| 44 | +--- |
48 | 45 |
|
49 | | -## Your First Reactive Widget |
| 46 | +## Quick Example |
50 | 47 |
|
51 | | -Here's a simple counter that rebuilds automatically when the count changes: |
| 48 | +<strong>Step 1:</strong> Register your reactive objects with get_it: |
52 | 49 |
|
53 | 50 | <<< @/../code_samples/lib/watch_it/counter_simple_example.dart#example |
54 | 51 |
|
55 | | -That's it! When you press the button, the widget automatically rebuilds with the new count. |
| 52 | +<strong>Step 2:</strong> Use `WatchingWidget` and watch your data: |
56 | 53 |
|
57 | | -## How It Works |
| 54 | +The widget automatically rebuilds when the counter value changes - no `setState` needed! |
58 | 55 |
|
| 56 | +<strong>How it works:</strong> |
59 | 57 | 1. **`WatchingWidget`** - Like `StatelessWidget`, but with reactive superpowers |
60 | 58 | 2. **`watchValue()`** - Watches data from get_it and rebuilds when it changes |
61 | 59 | 3. **Automatic subscriptions** - No manual listeners, no cleanup needed |
62 | 60 |
|
63 | 61 | The widget automatically subscribes to changes when it builds and cleans up when disposed. |
64 | 62 |
|
65 | | -## Adding to Your Existing App |
| 63 | +--- |
| 64 | + |
| 65 | +## Adding to Existing Apps |
66 | 66 |
|
67 | 67 | Already have an app? Just add a mixin to your existing widgets: |
68 | 68 |
|
|
0 commit comments