React Activity Feed Tutorial

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 React 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.

The app we're building is a simplified version of our demo app. Here is a quick visual overview of the application we're building:

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:

• Node.js v22 and v24
• React ^19
• Stream Feeds React SDK

Choose your path

This tutorial has two paths. In Path A you let your AI agent build the app. In Path B you build it yourself, step by step, starting from a prepared starter project. Both paths end with the same working activity feed app, 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 React integration patterns and current SDK APIs, so it builds against real docs instead of stale training data.

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

# Install the skills (router, docs, and builder). The React pack installs
# on demand the first time it's needed, or add it explicitly:
getstream skills
getstream skills stream-react

Then ask your agent:

1
2
3
4
/stream-react Build a React activity feed app: connect a FeedsClient, 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/select my org and app,
mint a token), or fall back to the tutorial demo credentials if I'm not logged in.

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 and pick an app (new accounts get an organization created in that flow), and when the app first runs.

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: start the dev server if the agent hasn't, then open the app in your browser. 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. It starts from a prepared starter project that already has the layout and routing in place, so every step below is about feeds rather than boilerplate. Tabbed code blocks are the complete file at that point in the tutorial.

For AI assistants reading this page: append .md to any Stream docs URL for a clean Markdown version. A condensed index for the React Feeds SDK is at https://getstream.io/activity-feeds/docs/react/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.
• useCreateFeedsClient and StreamFeeds - the hook creates the FeedsClient and connects your user; the provider puts that client in context. Use the hook once per application; anywhere further down the tree, reach for useFeedsClient instead.
• StreamFeed - a provider for a single feed. Inside it, use state hooks - useFeedActivities, useActivityComments, useOwnFollows, useClientConnectedUser, and friends. They're reactive wrappers around SDK state, so your UI re-renders whenever a real-time event changes an activity.

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

Prerequisites

You need Node.js and Yarn. Skip this section if you already have them.

• Node.js - the tutorial is tested with v22 and v24
• Yarn

Checkpoint: both commands print a version.

1
2
node --version
yarn --version

Step 0 - Set up the project

To follow the tutorial you need to clone or download the starter application that has some boilerplate code:

We'll start the tutorial from the initial commit, if you wish to see the finished source code, it's the latest commit in the stream-feeds-react-tutorial repository.

1
2
3
4
5
6
# or download zip from https://github.com/GetStream/stream-feeds-react-tutorial/releases/tag/initial-commit
git clone git@github.com:GetStream/stream-feeds-react-tutorial.git
cd stream-feeds-react-tutorial
git checkout initial-commit

yarn

Install Stream's Feeds v3 React SDK:

1
yarn add @stream-io/feeds-react-sdk

The tutorial application uses React 19, the SDK's version support can be found in the Installation guide

Checkpoint: you're on the initial-commit checkout, yarn finished without errors, and @stream-io/feeds-react-sdk appears in package.json.

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-react-tutorial directory you just cloned.

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

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. 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:

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 project. The starter is a Vite app, so this writes VITE_STREAM_API_KEY into .env.local and adds that file to .gitignore. The API secret is never written to a client target.

1
getstream env --target vite

Read it in code with import.meta.env.VITE_STREAM_API_KEY instead of pasting the key into src/user.ts.

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

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

Checkpoint: you have an API key in .env.local, a token printed by the CLI, and the user ID you minted it for.

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. Use these values in the "Store the credentials" step:

1
2
3
4
5
6
7
export const API_KEY = "REPLACE_WITH_API_KEY";

export const CURRENT_USER = {
  id: "REPLACE_WITH_USER_ID",
  name: "REPLACE_WITH_USER_NAME",
  token: "REPLACE_WITH_TOKEN",
};

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

Store the credentials

Whichever option you picked, replace the contents of the src/user.ts file with your values:

1
2
3
4
5
6
7
export const API_KEY = "<your API key>";

export const CURRENT_USER = {
  id: "<your user id>",
  name: "<your user name>",
  token: "<your user token>",
};

On Option 1, read the API key from .env.local instead of hardcoding it:

1
export const API_KEY = import.meta.env.VITE_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.

Run the application:

1
yarn dev

For now, the application doesn't do much, but this will change as we complete the tutorial step by step.

Checkpoint: src/user.ts holds non-placeholder values, the API key and token belong to the same Stream app, and the dev server starts without console errors.

Step 2 - Connect the user

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

The starter application you cloned has all necessary files, but they're empty. You can update their content from the code snippets in the tutorial. No need to create any additional files.

To achieve this, we're using the useCreateFeedsClient hook and StreamFeeds context provider to make sure all components have access to the client instance. Let's update App.tsx:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { StreamFeeds, useCreateFeedsClient } from "@stream-io/feeds-react-sdk";
import { AppSkeleton } from "./AppSkeleton";
import { API_KEY, CURRENT_USER } from "./user";

export default function App() {
  const client = useCreateFeedsClient({
    apiKey: API_KEY,
    tokenOrProvider: CURRENT_USER.token,
    userData: {
      id: CURRENT_USER.id,
      name: CURRENT_USER.name,
    },
  });

  if (!client) {
    return null;
  }

  return (
    <StreamFeeds client={client}>
      <AppSkeleton />
    </StreamFeeds>
  );
}

For simplicity, the tutorial doesn't handle errors. In a real application, you should always make sure to handle errors from API requests. The Error handling guide provides more information on this topic.

Checkpoint: the app renders its skeleton instead of a blank page. Stuck on a blank page? 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 below code snippet has some React boilerplate, this is the stripped down version to showcase the concept clearly (no need to add this to your app yet):

1
2
3
4
5
6
7
8
9
10
11
12
13
// SDK hooks for accessing client and connected user
const client = useFeedsClient();
const connectedUser = useClientConnectedUser();

// Using user id for the feed id, but you can use any id you want to
const ownFeed = client.feed("user", connectedUser.id);
await ownFeed.getOrCreate({
  // Turns on real-time updates
  watch: true,
});

const ownTimeline = client.feed("timeline", connectedUser.id);
await ownTimeline.getOrCreate({ watch: true, limit: 10 });

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

1
2
3
4
5
6
7
// You typically create these relationships on your server-side, we do this here for simplicity
const alreadyFollows = ownFeed.currentState.own_follows?.find(
  (follow) => follow.source_feed.feed === ownTimeline.feed,
);
if (!alreadyFollows) {
  ownTimeline.follow(ownFeed);
}

To make sure the user's feeds are easily accessible throughout the application, we create a React context provider for initializing feeds (own-feeds-context.tsx) and add this to App.tsx. This is the full code that contains the React boilerplate, add this to your application:

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
import {
  Feed,
  useClientConnectedUser,
  useFeedsClient,
} from "@stream-io/feeds-react-sdk";
import {
  createContext,
  PropsWithChildren,
  useContext,
  useEffect,
  useState,
} from "react";

type OwnFeedsContextValue = {
  ownFeed: Feed | undefined;
  ownTimeline: Feed | undefined;
};

const OwnFeedsContext = createContext<OwnFeedsContextValue>({
  ownFeed: undefined,
  ownTimeline: undefined,
});

export const OwnFeedsContextProvider = ({ children }: PropsWithChildren) => {
  const [ownFeed, setOwnFeed] = useState<Feed>();
  const [ownTimeline, setOwnTimeline] = useState<Feed>();
  const client = useFeedsClient();
  const connectedUser = useClientConnectedUser();

  useEffect(() => {
    if (!connectedUser || !client) return;

    const feed = client.feed("user", connectedUser.id);
    setOwnFeed(feed);

    const timeline = client.feed("timeline", connectedUser.id);
    setOwnTimeline(timeline);

    Promise.all([
      feed.getOrCreate({ watch: true }),
      timeline.getOrCreate({ watch: true, limit: 10 }),
    ]).then(() => {
      // You typically create these relationships on your server-side, we do this here for simplicity
      const alreadyFollows = feed.currentState.own_follows?.find(
        (follow) => follow.source_feed.feed === timeline.feed,
      );
      if (!alreadyFollows) timeline.follow(feed);
    });

    return () => {
      setOwnFeed(undefined);
      setOwnTimeline(undefined);
    };
  }, [connectedUser, client]);

  return (
    <OwnFeedsContext.Provider value={{ ownFeed, ownTimeline }}>
      {children}
    </OwnFeedsContext.Provider>
  );
};

export const useOwnFeedsContext = () => useContext(OwnFeedsContext);

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
import { StreamFeeds, useCreateFeedsClient } from "@stream-io/feeds-react-sdk";
import { AppSkeleton } from "./AppSkeleton";
import { API_KEY, CURRENT_USER } from "./user";
import { OwnFeedsContextProvider } from "./own-feeds-context";

export default function App() {
  const client = useCreateFeedsClient({
    apiKey: API_KEY,
    tokenOrProvider: CURRENT_USER.token,
    userData: {
      id: CURRENT_USER.id,
      name: CURRENT_USER.name,
    },
  });

  if (!client) {
    return null;
  }

  return (
    <StreamFeeds client={client}>
      <OwnFeedsContextProvider>
        <AppSkeleton />
      </OwnFeedsContextProvider>
    </StreamFeeds>
  );
}

Checkpoint: the app still renders without console errors. Seeing a "feed group not found" error? Feed group ids are case-sensitive.

Step 4 - Activity list

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

• Activity component - this will be very simple for now, and we'll extend it during the tutorial
• ActivityList component to display activities, and paginate
• We display the user's timeline feed on the Home page

The Activity component for now contains the most basic activity information (for example activity.text) and some HTML code to create a layout we can extend with new features.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { ActivityResponse } from "@stream-io/feeds-react-sdk";

export const Activity = ({ activity }: { activity: ActivityResponse }) => {
  return (
    <div className="w-full p-4 bg-base-100 card border border-base-300">
      <div className="w-full flex items-start gap-4">
        <div className="avatar flex-shrink-0">
          <div className="w-10 h-10 rounded-full bg-gradient-to-br from-primary to-secondary  flex items-center justify-center text-white text-lg font-semibold">
            <span>{activity.user?.name?.[0]}</span>
          </div>
        </div>
        <div className="w-full flex flex-col items-start gap-4">
          <div className="flex flex-row items-center gap-2">
            <span className="font-semibold text-md">{activity.user.name}</span>
            <span className="text-sm text-base-content/80">
              {activity.created_at.toLocaleString()}
            </span>
          </div>
          <p className="w-full">{activity.text}</p>
        </div>
      </div>
    </div>
  );
};

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
import { useFeedActivities } from "@stream-io/feeds-react-sdk";
import { Activity } from "./Activity";

export const ActivityList = () => {
  const { activities, loadNextPage, has_next_page } = useFeedActivities();

  return (
    <div className="w-full flex flex-col items-center justify-start gap-4">
      {activities?.length === 0 ? (
        "No posts yet"
      ) : (
        <>
          {activities?.map((activity) => (
            <Activity activity={activity} key={activity.id} />
          ))}
          {has_next_page && (
            <button className="btn btn-soft btn-primary" onClick={loadNextPage}>
              Load more
            </button>
          )}
        </>
      )}
    </div>
  );
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { StreamFeed } from "@stream-io/feeds-react-sdk";
import { useOwnFeedsContext } from "../own-feeds-context";
import { ActivityList } from "../components/activity/ActivityList";

export const Home = () => {
  const { ownTimeline } = useOwnFeedsContext();

  if (!ownTimeline) {
    return null;
  }

  return (
    <div className="w-full flex flex-col items-center justify-start gap-4">
      <StreamFeed feed={ownTimeline}>
        <ActivityList />
      </StreamFeed>
    </div>
  );
};

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

• We're using the StreamFeed context to make ownTimeline accessible to all components in a given subtree
• Components then can use useFeedContext and useFeedActivities hooks to access the data they need
  • You can find the full list of feed state hooks on the Contexts and Hooks page of the documentation

Checkpoint: the Home page renders "No posts yet" instead of a blank area. Nothing at all on screen? Home returns null until ownTimeline is set, so confirm OwnFeedsContextProvider wraps AppSkeleton in App.tsx.

Step 5 - Activity composer

Let's create an ActivityComposer component to be able to post, and add it to the Home page:

As mentioned previously: users post on their user feed, and it automatically appears in their timeline feed via follow relationship.

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
import { useFeedContext } from "@stream-io/feeds-react-sdk";
import { useCallback, useState } from "react";

export const ActivityComposer = () => {
  const feed = useFeedContext();
  const [newText, setNewText] = useState("");

  const sendActivity = useCallback(async () => {
    await feed?.addActivity({
      text: newText,
      // Type can be any string you want
      type: "post",
    });
    setNewText("");
  }, [feed, newText]);

  return (
    <div className="w-full p-4 bg-base-100 card border border-base-300">
      <div className="w-full flex flex-col gap-2">
        <textarea
          className="w-full textarea textarea-ghost flex-1 min-h-[60px] text-base"
          rows={3}
          placeholder="What is happening?"
          value={newText}
          onChange={(e) => setNewText(e.target.value)}
          style={{ resize: "none" }}
        />
        <div className="w-full flex justify-end items-center gap-2">
          <button
            className="btn btn-primary flex-shrink-0"
            onClick={sendActivity}
            disabled={!newText}
          >
            Post
          </button>
        </div>
      </div>
    </div>
  );
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { StreamFeed } from "@stream-io/feeds-react-sdk";
import { useOwnFeedsContext } from "../own-feeds-context";
import { ActivityComposer } from "../components/activity/ActivityComposer";
import { ActivityList } from "../components/activity/ActivityList";

export const Home = () => {
  const { ownTimeline, ownFeed } = useOwnFeedsContext();

  if (!ownTimeline || !ownFeed) {
    return null;
  }

  return (
    <div className="w-full flex flex-col items-center justify-start gap-4">
      <StreamFeed feed={ownFeed}>
        <ActivityComposer />
      </StreamFeed>
      <StreamFeed feed={ownTimeline}>
        <ActivityList />
      </StreamFeed>
    </div>
  );
};

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 a page refresh. 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.

The layout is similar to the Home page, we're reusing the ActivityList component, but there is no composer. Code for Explore.tsx:

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
import {
  useFeedsClient,
  useClientConnectedUser,
  StreamFeed,
} from "@stream-io/feeds-react-sdk";
import { useEffect, useMemo } from "react";
import { ActivityList } from "../components/activity/ActivityList";

export const Explore = () => {
  const client = useFeedsClient();
  const currentUser = useClientConnectedUser();
  const feed = useMemo(() => {
    if (!currentUser?.id || !client) {
      return undefined;
    }
    return client.feed("foryou", currentUser.id);
  }, [client, currentUser?.id]);

  useEffect(() => {
    if (feed) {
      feed.getOrCreate({ limit: 10 });
    }
  }, [feed]);

  if (!feed) {
    return null;
  }

  return (
    <StreamFeed feed={feed}>
      <ActivityList />
    </StreamFeed>
  );
};

You may have noticed that we don't use watch: true for this feed. This is because the foryou feed uses the "popular" activity selector, which doesn't support real-time updates. Adding watch:true won't cause an error, but does nothing here. 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:

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 reloading the page.

Checkpoint: the Explore page 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 adding:

• ToggleFollowButton component
• Extending the Activity component with the follow/unfollow button

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
import { useCallback } from "react";
import { useOwnFeedsContext } from "../own-feeds-context";
import {
  FeedResponse,
  useFeedsClient,
  useOwnFollows,
} from "@stream-io/feeds-react-sdk";

export const ToggleFollowButton = ({
  feed: feedResponse,
}: {
  feed: FeedResponse;
}) => {
  const client = useFeedsClient();
  const { ownTimeline } = useOwnFeedsContext();

  const feed = client?.feed(feedResponse.group_id, feedResponse.id);
  const { own_follows: ownFollows } = useOwnFollows(feed) ?? {};
  const isFollowing = (ownFollows?.length ?? 0) > 0;

  const follow = useCallback(async () => {
    if (!feed) return;

    await ownTimeline?.follow(feed);
    // Reload timelinesto see new activities
    await ownTimeline?.getOrCreate({ watch: true, limit: 10 });
  }, [feed, ownTimeline]);

  const unfollow = useCallback(async () => {
    if (!feed) return;

    await ownTimeline?.unfollow(feed);
    // Reload timeline to remove activities
    await ownTimeline?.getOrCreate({ watch: true, limit: 10 });
  }, [feed, ownTimeline]);

  const toggleFollow = useCallback(() => {
    if (isFollowing) {
      unfollow();
    } else {
      follow();
    }
  }, [isFollowing, feed, follow, unfollow]);

  return (
    <button
      className={`btn btn-soft ${
        isFollowing ? "btn-error" : "btn-primary"
      } btn-sm`}
      onClick={toggleFollow}
    >
      {isFollowing ? "Unfollow" : "Follow"}
    </button>
  );
};

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
import {
  ActivityResponse,
  useClientConnectedUser,
} from "@stream-io/feeds-react-sdk";
import { ToggleFollowButton } from "../ToggleFollowButton";

export const Activity = ({ activity }: { activity: ActivityResponse }) => {
  const currentUser = useClientConnectedUser();

  return (
    <div className="w-full p-4 bg-base-100 card border border-base-300">
      <div className="w-full flex items-start gap-4">
        <div className="avatar flex-shrink-0">
          <div className="w-10 h-10 rounded-full bg-gradient-to-br from-primary to-secondary  flex items-center justify-center text-white text-lg font-semibold">
            <span>{activity.user?.name?.[0]}</span>
          </div>
        </div>
        <div className="w-full flex flex-col items-start gap-4">
          <div className="flex flex-row items-center gap-2">
            <span className="font-semibold text-md">{activity.user.name}</span>
            <span className="text-sm text-base-content/80">
              {activity.created_at.toLocaleString()}
            </span>
            {activity.current_feed?.feed !== `user:${currentUser?.id}` && (
              <ToggleFollowButton feed={activity.current_feed!} />
            )}
          </div>
          <p className="w-full">{activity.text}</p>
        </div>
      </div>
    </div>
  );
};

Let's walk through the steps:

1. feed.follow and feed.unfollow lets us follow/unfollow feeds.
2. To immediately see the results of the follow/unfollow, we're reloading the timeline feed with getOrCreate.
3. In Activity component we're using activity.current_feed to know which feed the activity is posted to
   • activity.current_feed has information about the feed the activity was posted to. It's especially 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. useOwnFollows is used to determine if we're following a given feed or not
5. Stream API also supports follow requests where approval from feed owner is required to follow

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

Checkpoint: every activity that isn't yours shows a Follow button, clicking 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.current_feed check.

Step 8 - Reactions

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

To achieve this, we need to implement the ToggleReaction and extend the Activity component:

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
import { ActivityResponse, useFeedsClient } from "@stream-io/feeds-react-sdk";
import { useCallback } from "react";

export const ToggleReaction = ({
  activity,
}: {
  activity: ActivityResponse;
}) => {
  const client = useFeedsClient();

  const toggleReaction = useCallback(() => {
    activity.own_reactions?.length > 0
      ? client?.deleteActivityReaction({
          activity_id: activity.id,
          type: "like",
        })
      : client?.addActivityReaction({
          activity_id: activity.id,
          type: "like",
        });
  }, [client, activity.id, activity.own_reactions]);

  return (
    <button
      type="button"
      className={`btn ${
        activity.own_reactions?.length > 0 ? "bg-primary" : ""
      }`}
      onClick={toggleReaction}
    >
      ️&nbsp;
      {activity.reaction_groups["like"]?.count ?? 0}
    </button>
  );
};

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
import {
  ActivityResponse,
  useClientConnectedUser,
} from "@stream-io/feeds-react-sdk";
import { ToggleFollowButton } from "../ToggleFollowButton";
import { ToggleReaction } from "./ToggleReaction";

export const Activity = ({ activity }: { activity: ActivityResponse }) => {
  const currentUser = useClientConnectedUser();

  return (
    <div className="w-full p-4 bg-base-100 card border border-base-300">
      <div className="w-full flex items-start gap-4">
        <div className="avatar flex-shrink-0">
          <div className="w-10 h-10 rounded-full bg-gradient-to-br from-primary to-secondary  flex items-center justify-center text-white text-lg font-semibold">
            <span>{activity.user?.name?.[0]}</span>
          </div>
        </div>
        <div className="w-full flex flex-col items-start gap-4">
          <div className="flex flex-row items-center gap-2">
            <span className="font-semibold text-md">{activity.user.name}</span>
            <span className="text-sm text-base-content/80">
              {activity.created_at.toLocaleString()}
            </span>
            {activity.current_feed?.feed !== `user:${currentUser?.id}` && (
              <ToggleFollowButton feed={activity.current_feed!} />
            )}
          </div>
          <p className="w-full">{activity.text}</p>
          <div className="w-full flex flex-col gap-2">
            <div className="flex flex-row gap-2">
              <ToggleReaction activity={activity} />
            </div>
          </div>
        </div>
      </div>
    </div>
  );
};

Let's recap what we did in this step:

1. client.addActivityReaction and client.deleteActivityReaction toggles reactions
   • type can be any string you'd like
   • Since the React SDK provides reactive state management, the UI is automatically updated anytime anything on the activity changes
2. We use activity.own_reactions and activity.reaction_groups to get real-time reaction data for activity
3. Some advanced features not shown in tutorial:
   • A single user can add multiple reactions to an activity
   • Comments can have reactions too
   • Checkout 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, use the demo app to follow your tutorial user and 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:

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: each activity shows a reaction button with a count, clicking it increments the count and highlights the button, and clicking again removes the reaction. Ben's like from the CLI (or the demo app's) appears on your activity without a page refresh. The count doesn't move? The feed was read without watch: true, so no real-time events arrive.

Step 9 - Comments

Comments are another good way to add interactivity to your app. To add this feature, we need to do the following tasks:

• Implement CommentComposer to post comments
• Implement CommentList to list comments
• Extend Activity component to show comments

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
import { ActivityResponse, useFeedsClient } from "@stream-io/feeds-react-sdk";
import { useState, useCallback } from "react";

export const CommentComposer = ({
  activity,
}: {
  activity: ActivityResponse;
}) => {
  const client = useFeedsClient();
  const [commentDraft, setCommentDraft] = useState("");

  const addComment = useCallback(async () => {
    await client?.addComment({
      object_id: activity.id,
      object_type: "activity",
      comment: commentDraft,
    });
    setCommentDraft("");
  }, [client, activity.id, commentDraft]);

  return (
    <div className="w-full flex flex-row gap-2">
      <input
        className="input w-full"
        placeholder="Post your reply"
        value={commentDraft}
        onChange={(e) => setCommentDraft(e.target.value)}
      />
      <button
        className="btn btn-primary"
        onClick={addComment}
        disabled={!commentDraft.trim()}
      >
        Reply
      </button>
    </div>
  );
};

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
import {
  ActivityResponse,
  useActivityComments,
} from "@stream-io/feeds-react-sdk";
import { useEffect } from "react";

export const CommentList = ({ activity }: { activity: ActivityResponse }) => {
  const {
    comments = [],
    loadNextPage,
    has_next_page,
  } = useActivityComments({ activity });

  // Load initial comments
  useEffect(() => {
    if (comments.length === 0 && activity.comment_count > 0) {
      void loadNextPage({ limit: 5, sort: "best" });
    }
  }, [loadNextPage, comments.length, activity.comment_count]);
  return (
    <>
      {comments.map((comment) => (
        <div className="flex flex-row items-center gap-2" key={comment.id}>
          <span className="font-semibold">{comment.user.name}:</span>
          <span>{comment.text}</span>
        </div>
      ))}
      {activity.comment_count > 0 && has_next_page && (
        <button
          className="btn btn-soft btn-primary"
          onClick={() => loadNextPage()}
        >
          Load more comments
        </button>
      )}
    </>
  );
};

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
import {
  ActivityResponse,
  useClientConnectedUser,
} from "@stream-io/feeds-react-sdk";
import { ToggleFollowButton } from "../ToggleFollowButton";
import { ToggleReaction } from "./ToggleReaction";
import { CommentList } from "../comments/CommentList";
import { CommentComposer } from "../comments/CommentComposer";

export const Activity = ({ activity }: { activity: ActivityResponse }) => {
  const currentUser = useClientConnectedUser();

  return (
    <div className="w-full p-4 bg-base-100 card border border-base-300">
      <div className="w-full flex items-start gap-4">
        <div className="avatar flex-shrink-0">
          <div className="w-10 h-10 rounded-full bg-gradient-to-br from-primary to-secondary  flex items-center justify-center text-white text-lg font-semibold">
            <span>{activity.user?.name?.[0]}</span>
          </div>
        </div>
        <div className="w-full flex flex-col items-start gap-4">
          <div className="flex flex-row items-center gap-2">
            <span className="font-semibold text-md">{activity.user.name}</span>
            <span className="text-sm text-base-content/80">
              {activity.created_at.toLocaleString()}
            </span>
            {activity.current_feed?.feed !== `user:${currentUser?.id}` && (
              <ToggleFollowButton feed={activity.current_feed!} />
            )}
          </div>
          <p className="w-full">{activity.text}</p>
          <div className="w-full flex flex-col gap-2">
            <div className="flex flex-row gap-2">
              <button type="button" className="btn cursor-default">
                &nbsp;
                {activity.comment_count}
              </button>
              <ToggleReaction activity={activity} />
            </div>
            <CommentComposer activity={activity} />
            <CommentList activity={activity} />
          </div>
        </div>
      </div>
    </div>
  );
};

Let's recap what happened in this step:

1. client.addComment lets us create a comment
2. useActivityComments lets you read and paginate comments
   • Stream API provides multiple ways to sort comments
3. activity.comment_count stores how many comments the activity has

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 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:

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: each activity has a reply input, submitting a reply renders it under the activity, and the comment counter next to the reaction button goes up. Ben's reply from the CLI (or the demo app's) appears under your activity without a page refresh.

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:

• Implement FileUpload component to let users pick files, and upload it to Stream's CDN
• Extend the ActivityComposer to send attachments with the activity
• Extend the Activity component to display the attachment

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
import { useFeedsClient } from "@stream-io/feeds-react-sdk";
import { useCallback, useState } from "react";

export const FileUpload = ({
  onImageUploaded,
}: {
  onImageUploaded: (imageUrl: string) => void;
}) => {
  const client = useFeedsClient();
  const [isUploading, setIsUploading] = useState(false);

  const uploadImage = useCallback(
    async (file: File) => {
      if (!client) {
        return;
      }
      setIsUploading(true);
      try {
        const { file: image_url } = await client.uploadImage({ file });
        if (image_url) {
          onImageUploaded(image_url);
        }
      } finally {
        setIsUploading(false);
      }
    },
    [client, onImageUploaded],
  );

  const fileSelected = useCallback(
    (e: React.ChangeEvent<HTMLInputElement>) => {
      const file = e.target.files?.[0];
      if (!file) {
        return;
      }
      void uploadImage(file);
    },
    [uploadImage],
  );

  return (
    <label className="cursor-pointer">
      <div className="btn btn-secondary">
        {isUploading ? (
          <span className="loading loading-spinner loading-sm"></span>
        ) : (
          "Photo"
        )}
      </div>
      <input
        type="file"
        accept="image/*"
        className="hidden"
        onChange={fileSelected}
      />
    </label>
  );
};

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
import { useFeedContext } from "@stream-io/feeds-react-sdk";
import { useCallback, useState } from "react";
import { FileUpload } from "./FileUpload";

export const ActivityComposer = () => {
  const feed = useFeedContext();
  const [newText, setNewText] = useState("");
  const [imageUrl, setImageUrl] = useState<string | undefined>(undefined);

  const sendActivity = useCallback(async () => {
    await feed?.addActivity({
      text: newText,
      // Type can be any string you want
      type: "post",
      attachments: imageUrl
        ? [{ type: "image", image_url: imageUrl, custom: {} }]
        : [],
    });
    setNewText("");
    setImageUrl(undefined);
  }, [feed, newText, imageUrl]);

  return (
    <div className="w-full p-4 bg-base-100 card border border-base-300">
      <div className="w-full flex flex-col gap-2">
        <textarea
          className="w-full textarea textarea-ghost flex-1 min-h-[60px] text-base"
          rows={3}
          placeholder="What is happening?"
          value={newText}
          onChange={(e) => setNewText(e.target.value)}
          style={{ resize: "none" }}
        />
        {imageUrl && (
          <img
            src={imageUrl}
            alt="Uploaded image"
            className="w-50 h-50 object-cover rounded-lg"
          />
        )}
        <div className="w-full flex justify-end items-center gap-2">
          <FileUpload onImageUploaded={setImageUrl} />
          <button
            className="btn btn-primary flex-shrink-0"
            onClick={sendActivity}
            disabled={!newText}
          >
            Post
          </button>
        </div>
      </div>
    </div>
  );
};

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
import {
  ActivityResponse,
  useClientConnectedUser,
} from "@stream-io/feeds-react-sdk";
import { ToggleFollowButton } from "../ToggleFollowButton";
import { ToggleReaction } from "./ToggleReaction";
import { CommentList } from "../comments/CommentList";
import { CommentComposer } from "../comments/CommentComposer";

export const Activity = ({ activity }: { activity: ActivityResponse }) => {
  const currentUser = useClientConnectedUser();

  return (
    <div className="w-full p-4 bg-base-100 card border border-base-300">
      <div className="w-full flex items-start gap-4">
        <div className="avatar flex-shrink-0">
          <div className="w-10 h-10 rounded-full bg-gradient-to-br from-primary to-secondary  flex items-center justify-center text-white text-lg font-semibold">
            <span>{activity.user?.name?.[0]}</span>
          </div>
        </div>
        <div className="w-full flex flex-col items-start gap-4">
          <div className="flex flex-row items-center gap-2">
            <span className="font-semibold text-md">{activity.user.name}</span>
            <span className="text-sm text-base-content/80">
              {activity.created_at.toLocaleString()}
            </span>
            {activity.current_feed?.feed !== `user:${currentUser?.id}` && (
              <ToggleFollowButton feed={activity.current_feed!} />
            )}
          </div>
          <p className="w-full">{activity.text}</p>
          {activity.attachments.length > 0 && (
            <img
              src={activity.attachments[0].image_url}
              alt="Uploaded image"
              className="w-50 h-50 object-cover rounded-lg"
            />
          )}
          <div className="w-full flex flex-col gap-2">
            <div className="flex flex-row gap-2">
              <button type="button" className="btn cursor-default">
                &nbsp;
                {activity.comment_count}
              </button>
              <ToggleReaction activity={activity} />
            </div>
            <CommentComposer activity={activity} />
            <CommentList activity={activity} />
          </div>
        </div>
      </div>
    </div>
  );
};

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

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

Verify the whole build

1
yarn dev

Then open the app and confirm the full loop:

1. Post an activity on the Home page 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 - the reaction count and comment count both move.
4. Open the Explore page, 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

• Blank page, client never connects - check the console. An auth error usually means the API key and token belong to different apps.
• 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.
• stream project is not initialized - CLI onboarding hasn't run. Run getstream init in the project directory first.
• 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 page is empty - the foryou feed surfaces popular content, so it won't populate on a brand-new app with no reactions or comments yet.
• Feed group not found - feed group ids are case-sensitive and must exist on your app.
• Follow or unfollow doesn't change the timeline - the timeline is reloaded with getOrCreate after the toggle; without that reload the existing activities stay put until you reload the page.
• Nothing updates in real time - the feed was read without watch: true. Note that only the current_feed and following selectors deliver WebSocket events, which is why the foryou feed doesn't update live.
• Errors during a Next.js or Remix server render - the SDK is built for the browser and doesn't support server-side rendering. See the installation guide.

Next steps

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

• Activity selectors and ranking for customizing what content to show for users
• Activity processors for extracting topics from activity content
• Notification feeds (with aggregation)
• Story feed (activity expiration)
• Custom feed groups
• Feed and activity visibility including premium activities with feed memberships
• Moderation and fine-grained permission system
• Polls
• For more React examples, checkout stream-feeds-js repository
• Full list of supported Hooks and Contexts

Beyond the SDK itself:

• More platforms - the React Native tutorial covers mobile, and there are iOS, Android, and Flutter tutorials too
• Chat and video - Stream also powers chat and video, and they share the same client-side patterns
• Build with an AI agent - the Stream agent skills give your coding agent the current SDK APIs

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

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 and getstream skills stream-react for the web React pack. (Alternative: npx skills add GetStream/agent-skills -s stream.)
• Provisioning: getstream init (auth + create/select org & app) -> getstream env --target vite (writes VITE_STREAM_API_KEY to .env.local) -> getstream token <user-id> (mint a token)
• 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
• React integration skill: invoke /stream-react in your agent for React and Next.js setup patterns; /stream-docs searches live SDK docs with citations
• Docs index for LLMs: https://getstream.io/activity-feeds/docs/react/llms.txt
• Markdown endpoints: append .md to any docs URL for a clean, token-efficient version
• Source of truth for APIs: the SDK repository - check the installed version's source rather than assuming APIs from training data