Suggestion to update StreamBuilder documentation for best practices on Stream initialization - as already updated with FutureBuilder. #142189

Use case

According to the documentation on FutureBuilder the Future should be obtained during initState or the like):

The future must have been obtained earlier, e.g. during State.initState, State.didUpdateWidget, or State.didChangeDependencies. It must not be created during the State.build or StatelessWidget.build method call when constructing the FutureBuilder. If the future is created at the same time as the FutureBuilder, then every time the FutureBuilder's parent is rebuilt, the asynchronous task will be restarted.

The reason for is that otherwise, it would be refetched on every rebuild as explained in my StackOverflow Q&A

Proposal

Just as the FutureBuilder documentation advises initializing the future in initState or an equivalent lifecycle method, I believe it would be highly beneficial for the StreamBuilder documentation to include similar guidance. This would help prevent common pitfalls, such as streams being recreated on every build, leading to unnecessary rebuilds and potential performance issues.

I propose adding a section or note to the StreamBuilder documentation emphasizing the importance of initializing the stream in a stable manner, similar to the advice given for FutureBuilder. This could include a brief explanation and a code snippet demonstrating the recommended practice.

Such an update would greatly assist developers in understanding and implementing StreamBuilder more effectively, ensuring more robust and efficient Flutter applications.

Related:

• packages/flutter/lib/src/widgets/async.dart video promotes bad use of FutureBuilder #112676