Build multi-modal AI applications using our new open-source Vision AI SDK.

Stream logo
Start Coding Free

Flutter Activity Feed Tutorial

Ship cross-platform activity feeds with the Stream Activity Feeds Flutter SDK.
Follow this tutorial to build a single feed experience for iOS and Android using Flutter, with real-time updates and scalable infrastructure.

Prefer to skip the setup? Add the Stream skill and let your AI agent build your Flutter feed app.

Start Coding Free Install Sample App

Stream's Activity Feed V3 SDK enables teams of all sizes to build scalable activity feeds. This SDK is designed to enable you to get a feed application up and running quickly and efficiently while supporting customization for complex use cases.

In this tutorial, we will use Stream's Activity Feed V3 SDK for Flutter to:

  • Set up a simple activity feed application and connect it to Stream's Activity Feed V3 SDK.
  • Create user and timeline feeds.
  • Add activities, reactions and comments.
  • Explore new content with "For you" feed.

Here is a quick visual overview of the application we're building:

Stream Feeds Tutorial Overview

This page works for both humans and AI coding agents: every step is a file operation or a shell command, every step has a verification checkpoint, and the few steps that need a human are explicitly marked.

This tutorial has been tested with the following versions:

Choose your path

This tutorial has two paths. In Path A you let your AI agent build the app for you. In Path B you build it yourself, step by step, starting from a fresh Flutter project. Both paths end with a working activity feed app - Path A's is shaped by what you ask for, Path B's by the steps below - so pick one instead of working through both.

Path A - Let your AI agent build it (recommended)

Install the Stream CLI once, then add the skills. This gives Claude Code, Cursor, or Codex the Flutter integration patterns and current SDK APIs, so it builds against real docs instead of stale training data.

bash
1
2
3
4
5
6
7
8
9
# Install the getstream CLI
curl -fsSL https://getstream.io/cli.sh | bash

# Install the skills (router, docs, and builder) for your agent. Pick the
# target: --universal for Cursor, Codex, and other AGENTS-ecosystem tools,
# or --claude for Claude Code. The Flutter pack installs on demand the first
# time it's needed, or add it explicitly:
getstream skills --universal
getstream skills stream-flutter --universal

Then ask your agent:

Prompt (markdown)
1
2
3
4
/stream-flutter Build a Flutter activity feed app: connect a StreamFeedsClient, create user
and timeline feeds, render the timeline with an activity composer, and add reactions,
comments, and follow/unfollow. Provision credentials with the CLI: create or select my org
and app, then mint a token. If you can't mint one, ask me to provide fallback credentials.

Only the first line matters - /stream-flutter Build a Flutter activity feed app is enough to get going. The rest just steers the result: ask for a different tab split, your own theme, custom activity cards, or a notification feed instead of the Explore tab. Describe the app you want rather than the app the tutorial builds.

If the CLI can't mint credentials, provide the fallback ones from Step 1, Option 2 when the agent asks.

Where you come in. The agent handles credentials and code itself. It stops for you twice: when getstream init opens your browser to sign in, where a brand-new account creates your organization and first app in that same flow (if you already have an org or app, it lets you pick them instead), and when the app first runs on a simulator or emulator - launching one is a human call.

Want to get the sign-in out of the way first? Run getstream init before you prompt the agent - it picks up the initialized project from there.

Checkpoint: run the app if the agent hasn't (flutter run), then open it on your simulator or emulator. You should see your timeline and be able to post an activity.

Skim Important Building Blocks if you want to understand what the agent wrote before you extend it.

Path B - Build it manually

Choose this path if you'd rather write the code yourself, or you want to understand what the SDK is doing before you hand it to an agent. Some code blocks are complete files, others are edits to a file you already have - the text before each block says which.

For AI assistants reading this page: append .md to any Stream docs URL for a clean Markdown version. A condensed index for the Flutter Feeds SDK is at https://getstream.io/activity-feeds/docs/flutter/llms.txt. Prefer these over parsing HTML.

Important Building Blocks

Five pieces, one mental model:

  • Activities and feeds - an activity is the atomic unit of content (a post, a photo, a poll, or any custom type you define), and a feed is a collection of activities.
  • Feed groups - templates that decide how a feed behaves. Every app starts with the built-in user, timeline, foryou, notification, and story/stories feed groups. This tutorial uses the first three:
    • User Feed: A feed that contains all activities (posts) created by a specific user. Each user has their own user feed (e.g., user:alice).
    • Timeline Feed: A feed that contains activities from all the feeds that you follow. When you follow someone's user feed, their activities automatically appear in your timeline feed (this concept is called fan-out).
    • Follow Relationship: When you follow a user's feed, your timeline feed subscribes to their user feed. This means new activities from followed users automatically appear in your timeline.
  • StreamFeedsClient - the low-level client. It is bound to one user for its lifetime (the User and tokenProvider are fixed at construction). Built once, at app launch, and connect()ed before any feed call.
  • Feed and Activity - handles to a single feed or a single activity, obtained with client.feedFromId(FeedId.user(userId)) and client.activity(activityId: ..., fid: ...). Call getOrCreate() or get() to load them, and dispose() when you no longer need them.
  • Reactive state - feed.state gives you a snapshot (activities, following, canLoadMoreActivities, ...), while feed.notifier (with StateNotifierBuilder from flutter_state_notifier) or feed.stream keep your widgets in sync as real-time events arrive.

One difference from Stream's other SDKs: the Activity Feeds SDKs don't ship UI components. The SDK owns the client, the state, and the real-time updates; you own the views. That's why the steps below build small Flutter widgets of their own instead of dropping in ready-made ones.

You'll connect a client, create feeds, render a timeline, then layer on posting, discovery, follows, reactions, comments, and images.

Prerequisites

To follow the tutorial make sure you've installed Flutter and your IDE of choice. The tutorial is focused on Android and/or iOS, but can run on other platforms as well.

  • Flutter 3.27.4 or later on the stable channel, with Dart 3.6.2 or later - the minimum the stream_feeds package supports
  • Android Studio or VS Code
  • An iOS Simulator (via Xcode) or an Android emulator (via Android Studio)

Checkpoint: both commands succeed.

bash
1
2
flutter --version   # 3.27.4 or later
flutter doctor      # no blocking issues for your target platform

Step 0 - Set up the project

As a first step, you need to create a new Flutter project and install the dependencies we'll use in the tutorial.

If you wish to see the finished source code, it's the latest commit in the stream-feeds-flutter-tutorial repository.

bash
1
2
3
flutter create --empty stream_feeds_flutter_tutorial
cd stream_feeds_flutter_tutorial
flutter pub add stream_feeds image_picker flutter_state_notifier

Agents: detect the project shape first (find . -maxdepth 2 -name "pubspec.yaml"). If a Flutter project already exists, work in place instead of scaffolding a second one. If there is no project, stop and ask the human to create it - don't scaffold it yourself.

In the pubspec.yaml file you should see the stream_feeds, image_picker and flutter_state_notifier dependencies:

pubspec.yaml (yaml)
1
2
3
4
dependencies:
  stream_feeds: ^latest
  image_picker: ^latest
  flutter_state_notifier: ^latest

Checkpoint:

bash
1
2
flutter pub get   # resolves stream_feeds, image_picker, flutter_state_notifier
flutter analyze   # No issues found!

Step 1 - Get your credentials

The code in Step 2 needs a few values:

  • API_KEY - an API key that is used to identify your Stream application by our servers
  • id and token - authorization information of the current user
  • name - optional, used as a display name of the current user

There are two ways to get them. Pick one, then finish with the "Store the credentials" step.

Option 1 - Your own Stream app, via the Stream CLI

The getstream CLI provisions all of it in one flow. Run these from the stream_feeds_flutter_tutorial directory you just created.

1. Install the CLI (skip if you did this in Path A):

bash
1
curl -fsSL https://getstream.io/cli.sh | bash

2. Initialize the project. This one command authenticates you, lets you create or select an organization and app, and writes the project credentials. New to Stream? The sign-in flow creates your organization and your first app as you go. Already have an org or an app? It lets you pick them. The tutorial instructions assume an empty application so we suggest creating a new one:

bash
1
getstream init

Human checkpoint: getstream init opens a browser to authenticate. Agents: run it, then ask the human to finish signing in before continuing. It's required first - env, token, and api commands fail with "stream project is not initialized" until it runs.

3. Write your API key into the Flutter project. This writes the public API key to dart_defines.json (which it adds to .gitignore for you). The API secret is never printed or written into the app.

bash
1
getstream env --target flutter

4. Mint a user token for a user in your app (never expiring by default; add a TTL for production-like testing):

bash
1
2
getstream token alice
getstream token alice --ttl 1d

Checkpoint: dart_defines.json contains a STREAM_API_KEY entry, and you have a token printed by the CLI and the user id you minted it for, all belonging to your own app.

Learn more in the Tokens & Authentication documentation.

Option 2 - Pre-filled tutorial credentials, no account

Want to skip account setup entirely? To make the tutorial as easy as possible, we generated credentials for you to pick up and use. The block in "Store the credentials" below is already pre-filled with working credentials against Stream's shared, pre-seeded feeds tutorial environment - copy it as-is and it runs.

Swap in your own credentials from Option 1 before building anything real. Tutorial credentials are shared and short lived.

Store the credentials

To start using credentials, replace the contents of the main.dart file. You can remove everything that's already there and add the following:

main.dart (dart)
1
2
3
4
const String apiKey = 'REPLACE_WITH_API_KEY';
const String userId = 'REPLACE_WITH_USER_ID';
const String userToken = 'REPLACE_WITH_TOKEN';
const String name = 'REPLACE_WITH_USER_NAME';

On Option 1, paste the values the CLI gave you: the API key from dart_defines.json, and the user id and token from getstream token. If you'd rather not hardcode the key, read it from the define instead and launch with flutter run --dart-define-from-file=dart_defines.json:

dart
1
const String apiKey = String.fromEnvironment('STREAM_API_KEY');

Security Note: In production applications, never expose your API secret or generate tokens on the client side. Tokens should always be generated on your backend server to ensure security. The credentials in this tutorial are for development purposes only.

Checkpoint: main.dart holds non-placeholder values, and the API key and token belong to the same Stream app. The app won't run yet - main.dart is just these constants until Step 2 adds a main() function.

Step 2 - Connect the user

Let's create and connect the demo user to the Stream API.

To achieve this, we're creating a StreamFeedsClient and connect it while starting the app.

main.dart (dart)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import 'package:flutter/material.dart';
import 'package:stream_feeds/stream_feeds.dart';

const String apiKey = 'REPLACE_WITH_API_KEY';
const String userId = 'REPLACE_WITH_USER_ID';
const String userToken = 'REPLACE_WITH_TOKEN';
const String name = 'REPLACE_WITH_USER_NAME';

final client = StreamFeedsClient(
  apiKey: apiKey,
  user: User(id: userId, name: name),
  tokenProvider: TokenProvider.static(UserToken(userToken)),
);

Future<void> main() async {
  runApp(const Center(child: CircularProgressIndicator()));
  await client.connect();
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Stream Feeds Tutorial',
      home: const Placeholder(),
    );
  }
}

For simplicity, the tutorial doesn't handle errors. In a real application, you should always make sure to handle errors.

Checkpoint: the app launches and shows the placeholder screen instead of a stuck spinner. Still spinning? client.connect() failed - check the console for an auth error, which usually means the API key and token belong to different apps.

Step 3 - Create feeds

In this step we're creating a few feeds using built-in feed groups. The core concepts - user feeds, timeline feeds, and the follow relationship between them - are covered in Important Building Blocks.

Let's see what the concept looks like in code (no need to add this to your app yet):

dart
1
2
3
4
5
6
7
// Using user id for the feed id, but you can use any id you want to
final userFeed = client.feedFromId(FeedId.user(userId));
await userFeed.getOrCreate();

// This is our timeline feed where we want to see posts from people we follow
final timelineFeed = client.feedFromId(FeedId.timeline(userId));
await timelineFeed.getOrCreate();

Creating a Feed object sets up watching by default, so the feed receives real-time updates without any extra flag. To read a feed without subscribing, build it from a query instead: client.feedFromQuery(FeedQuery(fid: fid, watch: false)).

To ensure our own posts are part of our timeline, we need to set up the follow relationship:

dart
1
2
3
4
5
6
7
8
9
10
// You typically create these relationships on your server-side, we do this here for simplicity
final followsSelf =
    userFeed.state.feed?.ownFollows?.any(
      (follow) => follow.sourceFeed.fid == timelineFeed.fid,
    ) ??
    false;

if (!followsSelf) {
  await timelineFeed.follow(targetFid: userFeed.fid);
}

The two main screens of our app, Home and Explore, are going to be part of MyHomePage, so let's add code to create the feeds and dispose them there:

main.dart (dart)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Stream Feeds Tutorial',
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  bool isLoading = true;
  late final Feed userFeed;
  late final Feed timelineFeed;
  late final Feed exploreFeed;

  @override
  void initState() {
    super.initState();
    _loadFeeds();
  }

  Future<void> _loadFeeds() async {
    userFeed = client.feedFromId(FeedId.user(userId));
    await userFeed.getOrCreate();

    timelineFeed = client.feedFromId(FeedId.timeline(userId));
    await timelineFeed.getOrCreate();

    final followsSelf =
        userFeed.state.feed?.ownFollows?.any(
          (follow) => follow.sourceFeed.fid == timelineFeed.fid,
        ) ??
        false;

    if (!followsSelf) {
      await timelineFeed.follow(targetFid: userFeed.fid);
    }
    setState(() {
      isLoading = false;
    });
  }

  @override
  void dispose() {
    userFeed.dispose();
    timelineFeed.dispose();
    super.dispose();
  }

  int _index = 0;

  @override
  Widget build(BuildContext context) {
    if (isLoading) {
      return Center(child: CircularProgressIndicator());
    }

    return Scaffold(
      appBar: AppBar(title: Text('Stream Feeds Tutorial')),
      body: _index == 0
          ? Placeholder()
          : Placeholder(),
      bottomNavigationBar: BottomNavigationBar(
        items: [
          BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Home'),
          BottomNavigationBarItem(icon: Icon(Icons.search), label: 'Explore'),
        ],
        currentIndex: _index,
        onTap: (index) => setState(() => _index = index),
      ),
    );
  }
}

Checkpoint: the app renders the bottom navigation bar with Home and Explore tabs. Seeing a "feed group doesn't exist" error? Feed group ids are case-sensitive and must match the groups on your dashboard.

Step 4 - Activity list

Now that we created feeds, we can create UI components to display the activities. To achieve this we're creating an ActivityItem component.

For now, the ActivityItem displays only the most basic activity information (for example activity.text) and parameters that will be relevant in a bit, when we'll extend it with more features. We'll create new files: activity_item.dart and activity_list_view.dart and add the following code:

activity_item.dart
activity_list_view.dart
main.dart
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import 'package:flutter/material.dart';
import 'package:stream_feeds/stream_feeds.dart';

class ActivityItem extends StatelessWidget {
  const ActivityItem({
    super.key,
    required this.currentUserId,
    required this.activity,
    required this.onFollow,
    required this.onUnfollow,
    required this.onCommentPressed,
    required this.onLikePressed,
  });

  final String currentUserId;
  final ActivityData activity;
  final ValueSetter<FeedId> onFollow;
  final ValueSetter<FeedId> onUnfollow;
  final VoidCallback onCommentPressed;
  final VoidCallback onLikePressed;

  @override
  Widget build(BuildContext context) {
    return Text(activity.text ?? '');
  }
}

The activity list is currently empty. We'll change that in the next step. Before doing that, let's recap what we did in this step:

  • We created an instance of StreamFeedsClient for our user (1 instance maps to 1 user)
  • We used the client to create userFeed and timelineFeed, representing the feeds of the user's own activities and followed users' activities respectively
  • We created an ActivityItem component and used it to display the activities from the timeline feed's state
    • feed.notifier is a StateNotifier that automatically updates when activities are updated

Checkpoint: the Home tab renders "No posts yet" instead of a placeholder. Still on the loading spinner? _loadFeeds didn't finish - search the console for ClientException to see which getOrCreate() failed.

Step 5 - Activity composer

Let's add an ActivityComposer component and add it with a Column to the first tab of MyHomePage:

As mentioned previously: users post on their user feed and their posts automatically appear in their timeline feed via follow relationship.

activity_composer.dart
main.dart
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
import 'package:flutter/material.dart';
import 'package:stream_feeds/stream_feeds.dart';

class ActivityComposer extends StatefulWidget {
  const ActivityComposer({super.key, required this.userFeed});

  final Feed userFeed;

  @override
  State<ActivityComposer> createState() => _ActivityComposerState();
}

class _ActivityComposerState extends State<ActivityComposer> {
  final TextEditingController _controller = TextEditingController();
  bool _hasText = false;
  bool _isSending = false;

  @override
  void initState() {
    super.initState();
    _controller.addListener(() {
      final hasText = _controller.text.trim().isNotEmpty;
      if (_hasText != hasText) {
        setState(() => _hasText = hasText);
      }
    });
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: EdgeInsets.all(16),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          TextField(
            controller: _controller,
            decoration: InputDecoration(
              hintText: 'What is happening?',
              border: OutlineInputBorder(),
            ),
          ),
          SizedBox(height: 8),
          Row(
            mainAxisAlignment: MainAxisAlignment.end,
            children: [
              ElevatedButton(
                onPressed: _hasText && !_isSending ? _createActivity : null,
                child: Text('Post'),
              ),
            ],
          ),
        ],
      ),
    );
  }

  Future<void> _createActivity() async {
    // TODO: implement posting logic
  }
}

With the UI ready, we can implement the posting logic in the ActivityComposer. To do that, we just need to replace the _createActivity function stub with the actual implementation:

activity_composer.dart (dart)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
  Future<void> _createActivity() async {
    setState(() => _isSending = true);
    await widget.userFeed.addActivity(
      request: FeedAddActivityRequest(
        feeds: [widget.userFeed.fid.toString()],
        type: 'post',
        text: _controller.text,
      ),
    );
    _controller.clear();
    setState(() {
      _isSending = false;
    });
  }

Go ahead and post something! It'll automatically appear on your timeline.

Checkpoint: the composer appears above the activity list, the Post button is disabled until you type, and your post shows up in the list without restarting the app. Posted but nothing appeared? The activity went to your user feed but your timeline doesn't follow it - see the follow relationship set up in Step 3.

Step 6 - Explore page

The "Explore" page uses the foryou feed to explore new content by showing popular activities.

Just like we did for other feeds, we are going to add an exploreFeed to _MyHomePageState and initialize it accordingly in the loadFeeds function:

main.dart (dart)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
  Future<void> _loadFeeds() async {
    userFeed = client.feedFromId(FeedId.user(userId));
    await userFeed.getOrCreate();

    timelineFeed = client.feedFromId(FeedId.timeline(userId));
    await timelineFeed.getOrCreate();

    final followsSelf =
        userFeed.state.feed?.ownFollows?.any(
          (follow) => follow.sourceFeed.fid == timelineFeed.fid,
        ) ??
        false;

    if (!followsSelf) {
      await timelineFeed.follow(targetFid: userFeed.fid);
    }

    exploreFeed = client.feedFromId(FeedId(group: 'foryou', id: userId));
    await exploreFeed.getOrCreate();
    setState(() {
      isLoading = false;
    });
  }

  @override
  void dispose() {
    userFeed.dispose();
    timelineFeed.dispose();
    exploreFeed.dispose();
    super.dispose();
  }

Now we're ready to implement the "Explore" page UI. The layout is similar to Home tab, except that we're not adding the activity composer:

main.dart (dart)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
  @override
  Widget build(BuildContext context) {
    if (isLoading) {
      return Center(child: CircularProgressIndicator());
    }

    return Scaffold(
      appBar: AppBar(title: Text('Stream Feeds Tutorial')),
      body: _index == 0
          ? Column(
              children: [
                ActivityComposer(userFeed: userFeed),
                Expanded(
                  child: ActivityListView(
                    client: client,
                    feed: timelineFeed,
                    onFollow: onFollow,
                    onUnfollow: onUnfollow,
                  ),
                ),
              ],
            )
          : ActivityListView(
              client: client,
              feed: exploreFeed,
              onFollow: onFollow,
              onUnfollow: onUnfollow,
            ),
      bottomNavigationBar: BottomNavigationBar(
        items: [
          BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Home'),
          BottomNavigationBarItem(icon: Icon(Icons.search), label: 'Explore'),
        ],
        currentIndex: _index,
        onTap: (index) => setState(() => _index = index),
      ),
    );
  }

Note that the foryou feed uses the "popular" activity selector, which doesn't support real-time updates. The documentation details how real-time updates work.

Seed the Explore page on your own app

On the pre-filled tutorial credentials the Explore page already has activities to show - that environment is shared and pre-seeded. On your own app from the Stream CLI it will be empty: the foryou feed selects popular content, and a brand-new app has no activities, no users other than yours, and nothing to rank.

Seed it with the CLI. This lowers the popularity threshold so a single interaction is enough to qualify, creates a second user, and gives them a post:

Terminal (bash)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 1. Lower the popularity threshold on foryou
getstream api feeds UpdateFeedGroup --id foryou --request '{
  "activity_selectors": [
    { "type": "popular", "cutoff_window": "2d", "min_popularity": 1 },
    { "type": "following", "cutoff_window": "2d" },
    { "type": "follow_suggestion", "cutoff_window": "7d", "min_popularity": 5,
      "params": { "activities_per_feed": 2, "max_suggested_feeds": 10, "min_feed_score": 0.3 } }
  ]
}'

# 2. Create a new user: ben
getstream api common UpdateUsers --request '{"users":{"ben":{"id":"ben","name":"Ben","role":"user"}}}'

# 3. Set up Ben's feeds - auto-creates both timeline:ben and user:ben
getstream api feeds Follow --request '{"source":"timeline:ben","target":"user:ben"}'

# 4. Post an activity
getstream api feeds AddActivity --request '{
  "feeds": ["user:ben"],
  "type": "post",
  "text": "Hello from Ben!",
  "user_id": "ben",
  "id": "ben-first-post"
}'

# 5. Bookmark to boost popularity
getstream api feeds AddBookmark --activity-id ben-first-post --request '{"user_id":"ben"}'

Feed group changes can take up to 30 seconds to propagate to all API nodes, so give step 1 a moment before restarting the app.

Checkpoint: the Explore tab lists at least one activity you didn't post - Ben's on your own app, or the pre-seeded ones on the tutorial credentials. Don't skip this: the next step adds a follow button to activities from other users.

Step 7 - Follow and unfollow

To implement following and unfollowing feeds we're:

  • Performing the actual follow/unfollow operation in main.dart
  • Extending the ActivityItem component by adding the follow/unfollow button
main.dart
activity_item.dart
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
  Future<void> onFollow(FeedId value) async {
    await timelineFeed.follow(targetFid: value);
    // Ensure the feeds are up to date after follow/unfollow
    await timelineFeed.getOrCreate();
    await exploreFeed.getOrCreate();
  }

  Future<void> onUnfollow(FeedId value) async {
    await timelineFeed.unfollow(targetFid: value);
    // Ensure the feeds are up to date after follow/unfollow
    await timelineFeed.getOrCreate();
    await exploreFeed.getOrCreate();
  }

Let's walk through the steps:

  1. feed.follow and feed.unfollow let us follow/unfollow feeds.
  2. To immediately see the results of the follow/unfollow, we're reloading the feeds with getOrCreate.
  3. We're using activity.currentFeed.ownFollows to know if the user's timeline feed follows the feed or not.
    • activity.currentFeed has information about the feed the activity was posted to
    • It's useful if you're building Reddit-style applications where there is no 1:1 mapping between feeds and users
    • It lets you display name/image of the feed the activity belongs to
  4. The Stream API also supports follow requests where approval from the feed owner is required to follow

Now that the follow button is working, you can start following other users using the "Explore" page.

Checkpoint: every activity that isn't yours shows a Follow button, tapping it flips the label to Unfollow, and the followed user's activities appear on your Home timeline. Your own activities show no button at all - that's the activity.user.id != currentUserId check.

Step 8 - Reactions

To make our application more interactive, we'll add reactions for activities.

To achieve this, we'll follow the same approach we used for the follow button:

  • Implementing the "like" operation in activity_list_view.dart
  • Extend the ActivityItem component by adding the button to toggle a "like" reaction
activity_list_view.dart
activity_item.dart
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
        return ListView(
          children: [
            ...state.activities.map(
              (activity) => ActivityItem(
                currentUserId: client.user.id,
                activity: activity,
                onFollow: onFollow,
                onUnfollow: onUnfollow,
                onCommentPressed: () {},
                onLikePressed: () {
                  if (activity.ownReactions.isEmpty) {
                    feed.addActivityReaction(
                      activityId: activity.id,
                      request: AddReactionRequest(type: 'like'),
                    );
                  } else {
                    feed.deleteActivityReaction(
                      activityId: activity.id,
                      type: 'like',
                    );
                  }
                },
              ),
            ),
            if (feed.state.canLoadMoreActivities)
              TextButton(
                onPressed: () => feed.queryMoreActivities(),
                child: Text('Load more'),
              ),
          ],
        );

Let's do a recap of this step:

  1. We used feed.addActivityReaction and feed.deleteActivityReaction to toggle reactions
    • We used "like" as reaction type, but it can be any string you'd like
    • Since the Flutter SDK provides reactive state management, the UI is automatically updated anytime anything on the activity changes
  2. We use activity.ownReactions and activity.reactionGroups to get real-time reaction data for the activity
  3. Some advanced features not shown in the tutorial:
    • A single user can add multiple reactions to an activity
    • Comments can have reactions too
    • Check out the activity reactions and comment reactions pages in the documentation for more information

See a reaction arrive from someone else

Reacting to your own posts only proves the button works. To watch a reaction land in real time, you need a second user reacting to your activity.

On the pre-filled tutorial credentials, you can use the web demo app to follow your tutorial user, and to react to their activities.

On your own app from the Stream CLI, have Ben do it. This reads Alice's user feed as Ben, grabs the most recent activity, and likes it:

Terminal (bash)
1
2
3
4
5
6
7
8
9
10
# Read alice's feed as ben, grab the first activity's id and react with like
ACTIVITY_ID=$(getstream api feeds GetOrCreateFeed \
  --feed-group-id user --feed-id alice \
  --request '{"user_id":"ben","limit":1}' \
  --jq '.activities[0].id' | tr -d '"')

echo "$ACTIVITY_ID"

getstream api feeds AddActivityReaction --activity-id "$ACTIVITY_ID" \
  --request '{"type":"like","user_id":"ben","enforce_unique":true}'

Swap alice for the user id your own token belongs to - the one from Step 1 - so the like lands on an activity you can see in your running app. ben comes from the seeding commands in Step 6, so run those first if you skipped them. enforce_unique keeps a re-run from stacking duplicate likes.

Checkpoint: tapping the heart increments the count and turns it red; tapping again removes it. Ben's like from the CLI (or the demo app's) appears on your activity without restarting the app.

Step 9 - Comments

Comments are another good way to add interactivity to an app. To add this feature to the tutorial project we need to:

  • Implement CommentsPage and the components to display and post comments
  • Implement CommentComposer to post comments
  • Extend the ActivityItem component with a button to navigate to the comments screen
  • Extend the ActivityListView component to implement the navigation.
comments_page.dart
comment_composer.dart
activity_item.dart
activity_list_view.dart
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
import 'package:flutter/material.dart';
import 'package:flutter_state_notifier/flutter_state_notifier.dart';
import 'package:stream_feeds/stream_feeds.dart';

import 'comment_composer.dart';

class CommentsPage extends StatefulWidget {
  static MaterialPageRoute<void> route(
    StreamFeedsClient client,
    String activityId,
    FeedId feedId,
  ) {
    return MaterialPageRoute(
      builder: (context) =>
          CommentsPage(client: client, activityId: activityId, feedId: feedId),
    );
  }

  const CommentsPage({
    super.key,
    required this.client,
    required this.activityId,
    required this.feedId,
  });

  final StreamFeedsClient client;
  final String activityId;
  final FeedId feedId;

  @override
  State<CommentsPage> createState() => _CommentsPageState();
}

class _CommentsPageState extends State<CommentsPage> {
  late Activity activity;
  @override
  void initState() {
    super.initState();
    _loadActivity();
  }

  @override
  void didUpdateWidget(covariant CommentsPage oldWidget) {
    if (oldWidget.activityId != widget.activityId) {
      activity.dispose();
      _loadActivity();
    }
    super.didUpdateWidget(oldWidget);
  }

  @override
  void dispose() {
    activity.dispose();
    super.dispose();
  }

  Future<void> _loadActivity() async {
    activity = widget.client.activity(
      activityId: widget.activityId,
      fid: widget.feedId,
    );
    await activity.get();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Stream Feeds Tutorial')),
      body: Column(
        children: [
          Expanded(
            child: StateNotifierBuilder(
              stateNotifier: activity.notifier,
              builder: (context, state, child) {
                if (state.comments.isEmpty) {
                  return Center(child: Text('No comments yet'));
                }

                return ListView(
                  children: [
                    ...state.comments.map(
                      (comment) => CommentItem(comment: comment),
                    ),
                    if (activity.state.canLoadMoreComments)
                      TextButton(
                        onPressed: () => activity.queryMoreComments(),
                        child: Text('Load more'),
                      ),
                  ],
                );
              },
            ),
          ),
          CommentComposer(activity: activity),
        ],
      ),
    );
  }
}

class CommentItem extends StatelessWidget {
  const CommentItem({super.key, required this.comment});

  final CommentData comment;

  @override
  Widget build(BuildContext context) {
    return Card(
      margin: EdgeInsets.all(8),
      child: Padding(
        padding: EdgeInsets.all(16),
        child: Column(
          mainAxisSize: MainAxisSize.min,
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(
              comment.user.name ?? '',
              style: TextStyle(fontWeight: FontWeight.bold),
            ),
            SizedBox(height: 8),
            Text(comment.text ?? ''),
          ],
        ),
      ),
    );
  }
}

Let's recap what happened in this step:

  1. We instantiated an Activity object using client.activity and called .get() to load the activity data, including the comments
    • Notice this is very similar to what we did for Feed objects
  2. We posted new comments by calling activity.addComment
  3. We use activity.commentCount to display the total number of comments on an activity

See a reply arrive from someone else

As with reactions, replying to yourself only proves the composer works. To watch a reply land in real time, you need a second user commenting on your activity.

On the pre-filled tutorial credentials, use the web demo app to reply to your tutorial user's activities.

On your own app from the Stream CLI, have Ben do it. This reads Alice's user feed as Ben, grabs the most recent activity, and comments on it:

Terminal (bash)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Read alice's feed as ben, grab the first activity's id and comment
ACTIVITY_ID=$(getstream api feeds GetOrCreateFeed \
  --feed-group-id user --feed-id alice \
  --request '{"user_id":"ben","limit":1}' \
  --jq '.activities[0].id' | tr -d '"')

echo "$ACTIVITY_ID"

getstream api feeds AddComment --request '{
  "object_id": "'"$ACTIVITY_ID"'",
  "object_type": "activity",
  "comment": "Nice post, Alice!",
  "user_id": "ben"
}'

Same substitutions as in Step 8: swap alice for the user id your own token belongs to, and make sure ben exists from the Step 6 seeding commands.

Checkpoint: tapping the comment button opens the comments screen, submitting a reply renders it in the list, and the comment counter on the activity goes up. Ben's reply from the CLI (or the demo app's) appears without restarting the app.

Comments can be threaded/nested too (not shown in the tutorial).

Step 10 - Posting images

Stream API allows attaching files to activities and comments. Let's extend our app with attaching images to activities. To achieve this we need to:

  • Extend the ActivityComposer component to let users pick an image to attach and display a preview
  • Update the activity posting logic to include the attachment
  • Extend the Activity component to display the attachment
activity_composer.dart
activity_item.dart
new imports (dart)
1
2
3
import 'dart:io';

import 'package:image_picker/image_picker.dart';
dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class _ActivityComposerState extends State<ActivityComposer> {
  final TextEditingController _controller = TextEditingController();
  StreamAttachment? _attachment;
  bool _hasText = false;
  bool _isSending = false;

  @override
  void initState() {
    super.initState();
    _controller.addListener(() {
      final hasText = _controller.text.trim().isNotEmpty;
      if (_hasText != hasText) {
        setState(() => _hasText = hasText);
      }
    });
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: EdgeInsets.all(16),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          TextField(
            controller: _controller,
            decoration: InputDecoration(
              hintText: 'What is happening?',
              border: OutlineInputBorder(),
            ),
          ),
          SizedBox(height: 8),
          if (_attachment != null)
            Image.file(File(_attachment!.file.path), height: 100, width: 100),
          Row(
            mainAxisAlignment: MainAxisAlignment.end,
            children: [
              IconButton(
                onPressed: () {
                  _pickImage();
                },
                icon: Icon(Icons.image_outlined),
              ),
              SizedBox(width: 8),
              ElevatedButton(
                onPressed: (_hasText || _attachment != null) && !_isSending
                    ? _createActivity
                    : null,
                child: Text('Post'),
              ),
            ],
          ),
        ],
      ),
    );
  }

  Future<void> _createActivity() async {
    setState(() => _isSending = true);
    await widget.userFeed.addActivity(
      request: FeedAddActivityRequest(
        feeds: [widget.userFeed.fid.toString()],
        type: 'post',
        text: _controller.text,
        attachmentUploads: _attachment != null ? [_attachment!] : null,
      ),
    );
    _controller.clear();
    setState(() {
      _attachment = null;
      _isSending = false;
    });
  }

  Future<void> _pickImage() async {
    final image = await ImagePicker().pickImage(source: ImageSource.gallery);
    if (image != null) {
      final attachment = StreamAttachment(
        type: AttachmentType.image,
        file: AttachmentFile.fromXFile(image),
      );
      setState(() => _attachment = attachment);
    }
  }
}

Go ahead and post an image! Or send an image URL, as the Stream API can automatically attach URL metadata as an attachment.

Checkpoint: the image button opens the system picker, the selected image previews in the composer, and after posting it renders inside the activity.

Verify the whole build

bash
1
2
3
4
flutter analyze
flutter run
# or, if you used `getstream env --target flutter`:
flutter run --dart-define-from-file=dart_defines.json

Human checkpoint: launching on a simulator or device and confirming the UI is a human step. Agents: run flutter analyze and build, then hand back to the human to run it. Confirm the full loop:

  1. Post an activity on the Home tab and watch it appear on your timeline.
  2. Attach an image to a post, and paste a URL into another one to see the metadata attachment.
  3. Like your own activity and reply to it on the comments screen - the reaction count and comment count both move.
  4. Open the Explore tab, follow a user, and go back to Home to see their activities in your timeline.
  5. Unfollow them and confirm their activities leave your timeline.

Troubleshooting

  • stream project is not initialized - CLI onboarding hasn't run. Run getstream init in the project directory first.
  • token is invalid / auth error - the token was minted for a different app, or it expired. Re-mint with getstream token <user_id> and confirm the API key matches.
  • Stuck on the loading spinner - either client.connect() failed (Step 2) or one of the getOrCreate() calls in _loadFeeds did (Step 3), so isLoading never flips. Check the console; an auth error means the API key and token belong to different apps.
  • Did not find the file passed to "--dart-define-from-file" - dart_defines.json only exists after getstream env --target flutter runs. On the pre-filled tutorial credentials, launch with plain flutter run.
  • Timeline stays empty after posting - the timeline feed doesn't follow the user feed. The follow relationship in Step 3 sets this up; confirm it ran.
  • Explore tab is empty - the foryou feed surfaces popular content, so it won't populate on a brand-new app with no reactions or comments yet. Seed it with the Step 6 commands.
  • Feed group not found / empty feed - feed group ids are case-sensitive and must match the feed groups on your app. New apps have the built-in user, timeline, and foryou groups enabled; you can review or add them in the dashboard (Feeds -> Feed Groups).
  • Follow or unfollow doesn't change the timeline - the feeds are reloaded with getOrCreate after the toggle; without that reload the existing activities stay put until you restart the app.
  • Nothing updates in real time - note that only the current_feed and following selectors deliver WebSocket events, which is why the foryou feed doesn't update live.
  • The UI doesn't rebuild when data changes - the widget read feed.state once instead of binding to feed.notifier through StateNotifierBuilder. Snapshots don't rebuild; the notifier does.
  • APIs in this tutorial don't exist on the package you installed - check you added stream_feeds (plural). The similarly named stream_feed is the discontinued V2 package, and pub.dev lists stream_feeds as its replacement.

Next steps

Even though this was a long tutorial, Activity Feed V3 has even more features:

Beyond the SDK itself:

Pricing is flexible with multiple tiers, including a free maker plan for hobby projects and small companies.

Final Thoughts

In this tutorial, we built a fully-functioning Flutter activity feed application with Stream's Activity Feed V3 SDK. We showed how easy it is to:

  • Set up a simple activity feed application and connect it to Stream's Activity Feed V3 SDK.
  • Create user and timeline feeds.
  • Add activities, reactions and comments.
  • Explore new content with "For you" feed.

Machine-readable resources

For AI agents and coding assistants working with this SDK:

  • CLI + skills: curl -fsSL https://getstream.io/cli.sh | bash, then getstream skills --universal and getstream skills stream-flutter --universal for the Flutter pack (use --claude instead for Claude Code). (Alternative: npx skills add GetStream/agent-skills -s stream.)
  • Provisioning: getstream init (auth + create/select org & app) -> getstream env --target flutter (API key to dart_defines.json) -> getstream token <user_id> (mint a token); feed groups are configured in the dashboard
  • Data & config from the CLI: getstream api <Endpoint> --request '{...}' for users, feeds, activities, and follows - AddActivity, Follow, QueryFeeds, QueryActivities, UpdateFeedGroup. CastPollVote and DeletePollVote exist in both Chat and Feeds, so namespace those: getstream api feeds CastPollVote
  • Flutter integration skill: invoke /stream-flutter in your agent for Feeds setup patterns; /stream-docs searches live SDK docs with citations
  • Docs index for LLMs: https://getstream.io/activity-feeds/docs/flutter/llms.txt
  • Markdown endpoints: append .md to any docs URL for a clean, token-efficient version
  • Source of truth for APIs: the SDK repository - Feeds V3 is pre-1.0; check the pinned version's source rather than assuming APIs from training data

Give us feedback!

Did you find this tutorial helpful in getting you up and running with your project? Either good or bad, we're looking for your honest feedback so we can improve.

Start coding

If you're interested in a custom plan or have any questions, please contact us.

Start Coding Contact Sales