But in order to build such dynamic and efficient applications in Flutter, you’ll need a profound understanding of asynchronous programming. And within that domain, streams are an indispensable tool.

This comprehensive guide will delve deep into the world of streams in Flutter, demystifying their core concepts, illustrating their practical applications, and providing a wealth of code examples to solidify your understanding.

Table of Contents

1. Prerequisites

2. The Challenge of Asynchronous Operations

3. What are Streams? The Flow of Asynchronous Events

   • Analogy: The River of Data

4. Why Streams are Crucial in Flutter

5. Key Concepts of Streams

   • 1. StreamController

   • Types of Streams: Single-Subscription vs. Broadcast

   • 2. StreamBuilder

   • 3. StreamSubscription

   • Async Programming with Streams: async* and yield

6. How to Work with Streams: Practical Scenarios

   • 1. Transforming Streams: map, where, take, skip, and so on.

   • 2. Combining Streams

7. Real-World Examples in Flutter

   • 1. Fetching Data from a Network with Live Updates

   • 2. User Input Handling: Debouncing a Search Field

8. Best Practices and Considerations

9. Advanced Concepts (Brief Introduction)

10. Conclusion

11. References

    • Official Documentation

    • Key Packages

    • Articles and Tutorials (General)

    • Related State Management Patterns

    • HTTP Package (for Network Examples)

Prerequisites

Before we embark on this journey, make sure you have a basic understanding of:

1. Dart programming language: Familiarity with Dart's syntax, variables, functions, and object-oriented concepts.

2. Flutter fundamentals: Knowledge of Flutter widgets, StatefulWidget vs. StatelessWidget, and basic UI layout.

3. Asynchronous programming basics (Dart's Future): An understanding of what Future represents and how the async/await keywords work to handle single asynchronous operations. If you're new to Future, think of it as a placeholder for a value that will be available at some point in the future.

If you're comfortable with these concepts, you're well-prepared to explore the power of streams.

The Challenge of Asynchronous Operations

In modern applications, blocking the UI is bad. Imagine an app freezing while it fetches data from the internet, processes a large file, or performs a complex calculation. This leads to a frustrating user experience.

Traditional synchronous programming executes tasks sequentially. When a long-running task is encountered, the entire program waits for it to complete. Asynchronous programming, on the other hand, allows tasks to run in the background without blocking the main execution thread, particularly the UI thread.

Dart's Future class is excellent for handling single asynchronous events (for example, a single network request that returns a single piece of data). But what if you have a continuous flow of events? What if you need to listen for data updates over time, like real-time chat messages, sensor readings, or continuous user input? This is where Streams shine.

What are Streams? The Flow of Asynchronous Events

In Flutter (and Dart), a stream is fundamentally a sequence of asynchronous events. Think of it as a conveyor belt carrying data items over time. These events can be:

1. Data values: The actual information being transmitted (for example, integers, strings, custom objects).

2. Errors: Signals that something went wrong during the event sequence.

3. Stream termination: A signal indicating that no more events will be sent.

Streams provide a powerful reactive programming paradigm, allowing your application to react to events as they occur, without blocking the user interface. This enables the creation of highly responsive and efficient applications.

Analogy: The River of Data

Imagine a river. The water flowing in the river is like the data (events) in a stream.

• You can set up a listener (like a fishing net) to catch fish (data) as they flow by.

• Sometimes, debris (errors) might come down the river.

• Eventually, the river might dry up (stream termination).

This continuous flow is what makes streams distinct from Future objects, which represent a single "delivery" rather than a continuous "flow."

Why Streams are Crucial in Flutter

1. Real-time updates: Ideal for chat applications, live data feeds (stocks, weather), and sensor data.

2. Event handling: Managing continuous user input (for example, search bar suggestions), gestures, or notifications.

3. Decoupling logic: Separating data fetching/processing from UI rendering, leading to cleaner, more maintainable code.

4. State management: Many advanced Flutter state management solutions (like BLoC, Provider's StreamProvider) leverage Streams extensively.

Here's a visual representation of how a stream works:

Key Concepts of Streams

To effectively work with Streams, you need to understand a few core components:

1. StreamController

A StreamController is your primary tool for creating and managing streams. It acts as both a sink (where you add data/events to the stream) and a source (from which you can get the stream to listen to). It's the mechanism that allows you to "control" the flow of events into your stream.

The purpose of a StreamController is to create, manage, and add events (data, errors, done signals) to a stream.

Code sample:

import 'dart:async'; // Required for StreamController

void main() {
  // 1. Create a StreamController for String data
  //    The type argument <String> specifies the type of data this stream will emit.
  final streamController = StreamController<String>();

  // 2. Get the stream from the controller
  //    This is the stream that other parts of your application will listen to.
  Stream<String> myStream = streamController.stream;

  // 3. Listen to the stream
  //    The .listen() method registers a callback to handle incoming data.
  //    It returns a StreamSubscription, which can be used to manage the listener.
  var subscription = myStream.listen((data) {
    print('Received data: $data');
  });

  // 4. Add data to the stream
  //    Use the sink property of the controller to add events.
  streamController.sink.add('Hello');
  streamController.sink.add('Flutter');
  streamController.sink.add('Streams!');

  // 5. Simulate an error
  //    You can also add errors to the stream.
  streamController.sink.addError('Something went wrong!');

  // 6. Close the stream when you're done
  //    It's crucial to close the stream controller to prevent memory leaks.
  //    This also sends a "done" event to all listeners.
  streamController.close();

  // Optionally cancel the subscription if no longer needed before stream closes
  // subscription.cancel();
}

In this code:

The line final streamController = StreamController<String>(); initializes a StreamController designed to handle String data, though it can be created for any data type (for example, int, custom classes, and so on). The Stream<String> myStream = streamController.stream; statement retrieves the actual Stream that consumers, such as StreamBuilder widgets or other listeners, can subscribe to.

By calling myStream.listen((data) { ... });, you set up a listener that executes the provided callback function each time streamController.sink.add() is invoked with new data. To emit data, you use streamController.sink.add('Hello');, while streamController.sink.addError('Something went wrong!'); allows you to emit error events that listeners can respond to.

Finally, calling streamController.close(); is essential, as it notifies all listeners that the stream is complete and will emit no further events, while also freeing resources. Neglecting to close a controller can cause memory leaks, especially in long-running applications.

Types of Streams: Single-Subscription vs. Broadcast

Streams come in two flavors, each suited for different use cases:

1. Single-Subscription Streams (Default):

   • Purpose: Designed for a single listener. Once you listen() to it, you cannot listen again unless the first subscription is cancelled or the stream is created as a broadcast stream.

   • Use Cases: Data fetches (like a file read), HTTP responses where you only need one component to consume the result.

   • Example: When you call http.get(...).asStream(), you get a single-subscription stream.

2. Broadcast Streams:

   • Purpose: Allows multiple listeners to subscribe and receive events simultaneously. Events are delivered to all active listeners.

   • Use Cases: Real-time data updates where multiple UI widgets or logic components need the same information (for example, a global authentication status, real-time notifications).

   • Creation: You create a broadcast stream by passing broadcast: true to the StreamController constructor.

Code sample (Broadcast Stream):

import 'dart:async';

void main() async {
  // Create a StreamController that supports multiple listeners
  final broadcastController = StreamController<int>.broadcast();

  // Listener 1
  broadcastController.stream.listen((event) {
    print('Listener 1 received: $event');
  }, onError: (e) => print('Listener 1 error: $e'));

  // Listener 2 (can listen even while Listener 1 is active)
  broadcastController.stream.listen((event) {
    print('  Listener 2 received: $event');
  }, onError: (e) => print('  Listener 2 error: $e'));

  broadcastController.sink.add(1);
  await Future.delayed(Duration(milliseconds: 500)); // Simulate delay
  broadcastController.sink.add(2);
  await Future.delayed(Duration(milliseconds: 500));
  broadcastController.sink.addError('Broadcast error!');
  await Future.delayed(Duration(milliseconds: 500));
  broadcastController.sink.add(3);

  await Future.delayed(Duration(seconds: 1)); // Give time for events to process
  broadcastController.close(); // Close the controller, notifying all listeners
}

In final broadcastController = StreamController<int>.broadcast();, the key is .broadcast(). This ensures that multiple listen() calls on broadcastController.stream will all receive events. Both Listener 1 and Listener 2 independently subscribe and receive 1, 2, the error, and 3.

Choose the stream type carefully based on your application's needs. When in doubt, start with a single-subscription stream and convert to broadcast only if truly necessary, as broadcast streams can sometimes make debugging event flow more complex.

2. StreamBuilder

The StreamBuilder widget is Flutter's dedicated tool for integrating Streams directly into your UI. It's a StatefulWidget under the hood that listens to a stream and rebuilds its UI whenever new data, errors, or completion signals arrive. This makes your UI reactive to data changes without manually calling setState().

StreamBuilder automatically rebuilds a part of the UI in response to new data from a stream.

Code sample:

import 'package:flutter/material.dart';
import 'dart:async';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'StreamBuilder Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: StreamBuilderPage(),
    );
  }
}

class StreamBuilderPage extends StatefulWidget {
  @override
  _StreamBuilderPageState createState() => _StreamBuilderPageState();
}

class _StreamBuilderPageState extends State<StreamBuilderPage> {
  final _dataController = StreamController<int>();
  int _counter = 0;

  @override
  void initState() {
    super.initState();
    // Start adding data to the stream every second
    Timer.periodic(Duration(seconds: 1), (timer) {
      _counter++;
      _dataController.sink.add(_counter);
      if (_counter >= 5) {
        timer.cancel(); // Stop adding after 5 events
        _dataController.close(); // Close the stream
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('StreamBuilder Example')),
      body: Center(
        // StreamBuilder is the core widget here
        child: StreamBuilder<int>(
          stream: _dataController.stream, // The stream to listen to
          // initialData: 0, // Optional: A value to display before any stream data arrives
          builder: (context, snapshot) {
            // The builder function is called every time the stream emits a new event.
            // 'snapshot' contains the latest state of the stream.

            if (snapshot.connectionState == ConnectionState.waiting) {
              // Show a loading indicator while waiting for the first event
              return CircularProgressIndicator();
            } else if (snapshot.hasError) {
              // Display an error message if the stream emits an error
              return Text('Error: ${snapshot.error}', style: TextStyle(color: Colors.red));
            } else if (snapshot.hasData) {
              // Display the received data
              return Text(
                'Received Data: ${snapshot.data}',
                style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
              );
            } else {
              // This case might occur if the stream closes without sending data
              // or initialData wasn't provided and no data has arrived yet.
              return Text('No data yet or stream closed.');
            }
          },
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          // You could also add data from a button press, for instance
          // _dataController.sink.add(99);
        },
        child: Icon(Icons.add),
      ),
    );
  }

  @override
  void dispose() {
    // IMPORTANT: Close the StreamController when the widget is disposed
    // to prevent memory leaks.
    _dataController.close();
    super.dispose();
  }
}

This is a lot – so let’s explore what’s going on in this code:

A StreamBuilder<int>(stream: _dataController.stream, builder: (context, snapshot) { ... }) widget listens to a stream and rebuilds the UI in response to new events or connection state changes.

The stream parameter specifies the stream to listen to, while the builder function is called every time the stream emits a new event or changes state. It receives the BuildContext and an AsyncSnapshot<T>, which encapsulates the latest stream data and status.

The snapshot provides key details about the stream:

• snapshot.connectionState shows the current connection state, none (no stream connected), waiting (connected but no data yet), active (actively receiving events), and done (stream closed).

• snapshot.hasData and snapshot.data indicate whether the stream has emitted data and provide access to the most recent value.

• snapshot.hasError and snapshot.error handle errors emitted by the stream.

In the builder, conditional rendering (using if or switch statements) allows you to display appropriate UI for each state, such as loading indicators, error messages, or the actual data.

You can also specify initialData to provide a starting value before the first event arrives, avoiding unnecessary loading indicators if you already have a known initial state.

Finally, always close your StreamController in the widget’s dispose() method to prevent memory leaks when the widget is removed from the widget tree.

3. StreamSubscription

When you call stream.listen(), it returns a StreamSubscription object. This object represents the active connection between your listener and the stream. It's essential for managing the lifecycle of your listener.

StreamSubscription manages an active listener on a stream, primarily for cancelling it.

Code sample (already shown partially in StreamController example, but emphasizing StreamSubscription):

import 'dart:async';

void main() async {
  final streamController = StreamController<String>();

  StreamSubscription<String>? subscription; // Declare it nullable

  // Listen to the stream and store the subscription object
  subscription = streamController.stream.listen(
    (data) {
      print('Received data: $data');
      // After receiving 'Stop', cancel the subscription
      if (data == 'Stop') {
        print('Cancelling subscription...');
        subscription?.cancel(); // Use null-safe call
        streamController.close(); // Close the controller after stopping
      }
    },
    onError: (error) {
      print('Error: $error');
    },
    onDone: () {
      print('Stream is done (closed)!');
    },
    cancelOnError: false, // Don't cancel subscription if an error occurs
  );

  streamController.sink.add('Start');
  await Future.delayed(Duration(milliseconds: 500));
  streamController.sink.add('Continue');
  await Future.delayed(Duration(milliseconds: 500));
  streamController.sink.add('Stop'); // This will trigger cancellation

  // If the stream wasn't closed by 'Stop' logic, ensure it's closed here after a delay
  // await Future.delayed(Duration(seconds: 2));
  // if (!streamController.isClosed) {
  //   streamController.close();
  // }
}

In this code, a StreamSubscription<String>? subscription; variable is declared to hold the subscription to a stream. When subscription = streamController.stream.listen(...) is called, the listen method returns a StreamSubscription object that allows you to control the stream’s behavior.

The subscription?.cancel(); method is the most crucial part: it detaches the listener from the stream, preventing it from receiving further events. This is especially important for single-subscription streams or when you need to stop listening to a broadcast stream temporarily. Forgetting to cancel subscriptions, particularly in StatefulWidgets, can lead to memory leaks.

The listen method accepts several parameters:

• The first positional argument is the onData callback (triggered when new data arrives)

• onError is an optional callback for handling errors

• onDone is an optional callback for when the stream closes

• And cancelOnError is a boolean that, when true, automatically cancels the subscription after the first error, stopping all further events.

Async Programming with Streams: async* and yield

While StreamController gives you fine-grained control over adding events, Dart also provides a more declarative way to create streams using async* and yield. This syntax is similar to async/await for Futures but for continuous streams of data.

1. async* (async-generator function): A function marked with async* returns a Stream.

2. yield: Inside an async* function, yield is used to emit data events to the stream.

We use async* and yield to easily create streams by iteratively yielding data without manually managing a StreamController.

Code sample:

import 'dart:async';

// A function that returns a Stream of integers
Stream<int> countStream(int max) async* {
  for (int i = 1; i <= max; i++) {
    // Simulate some asynchronous work
    await Future.delayed(Duration(milliseconds: 500));
    // Yield (emit) the current value to the stream
    yield i;
  }
  // No explicit close() needed; the stream closes automatically when the function completes.
}

void main() {
  print('Starting stream...');
  // Listen to the stream generated by countStream
  final subscription = countStream(5).listen(
    (data) {
      print('Received: $data');
    },
    onDone: () {
      print('Stream is done!');
    },
    onError: (error) {
      print('Error in stream: $error');
    },
  );

  // You can still cancel the subscription manually if needed
  // Future.delayed(Duration(seconds: 2), () => subscription.cancel());
}

In this code, the Stream<int> countStream(int max) async* function uses the async* keyword to indicate that it returns a stream. Inside it, await Future.delayed(Duration(milliseconds: 500)); demonstrates that await can still be used within an async* function to pause execution until a future completes, enabling asynchronous operations during stream generation.

The yield i; statement is what adds each value to the stream. Every time it’s called, the value i is emitted as an event, and the function pauses until the next value is ready or requested.

When the function completes (for example, when the for loop finishes), the stream automatically closes and emits an onDone event to all listeners, making stream management simpler than using a StreamController manually.

This async*/yield syntax is particularly elegant for generating streams of data where the sequence is known or can be computed iteratively.

How to Work with Streams: Practical Scenarios

Let's explore common patterns and operations with streams.

1. Transforming Streams: map, where, take, skip, and so on.

Streams are powerful because they are iterable, meaning you can apply various transformations to their data flow using methods similar to those found on Dart's Iterables (List, Set).

import 'dart:async';

void main() async {
  final numbersController = StreamController<int>();

  // Create a stream that emits squares of numbers from another stream,
  // but only for even numbers, and only takes the first 3 results.
  numbersController.stream
      .where((number) => number % 2 == 0) // Only let even numbers pass
      .map((evenNumber) => evenNumber * evenNumber) // Transform even numbers to their squares
      .take(3) // Only take the first 3 squared even numbers
      .listen(
        (squaredEven) {
          print('Transformed data: $squaredEven');
        },
        onDone: () {
          print('Transformed stream is done!');
        },
        onError: (e) {
          print('Transformed stream error: $e');
        }
      );

  // Add some numbers to the source stream
  numbersController.sink.add(1);
  numbersController.sink.add(2); // Passes where, maps to 4, taken (1st)
  numbersController.sink.add(3);
  numbersController.sink.add(4); // Passes where, maps to 16, taken (2nd)
  numbersController.sink.add(5);
  numbersController.sink.add(6); // Passes where, maps to 36, taken (3rd)
  numbersController.sink.add(7);
  numbersController.sink.add(8); // Will not be processed due to .take(3)
  await Future.delayed(Duration(milliseconds: 100)); // Allow events to process

  numbersController.close();
}

In Dart streams, several transformation and filtering methods are available:

• .where(bool test(T element)) filters events based on a condition

• .map<R>(R convert(T event)) transforms each event from one type to another

• .take(int count) emits only the first specified number of events

• .skip(int count) ignores the first few events and emits the rest

• .distinct() allows only unique consecutive events to pass

• .first, .last, and .single return a Future that completes with the first, last, or single event respectively

• .fold<R>(R initialValue, R combine(R previous, T element)) accumulates values like reduce

• .asyncMap<R>(FutureOr<R> convert(T event)) applies asynchronous transformations to each event, making it useful for async operations on stream items.

These operators are incredibly powerful for manipulating and refining the data flow within your application.

2. Combining Streams

Sometimes you need to combine events from multiple streams.

1. Stream.fromFutures(Iterable<Future<T>> futures): Creates a stream that emits the results of multiple Future(s) as they complete.

2. StreamGroup (from package:async): A utility for combining multiple streams into a single stream, preserving the order of events from the original streams.

Code sample (Stream.fromFutures):

import 'dart:async';

Future<String> fetchUserData(String userId) async {
  await Future.delayed(Duration(seconds: 1));
  return 'User Data for $userId';
}

Future<String> fetchProductData(String productId) async {
  await Future.delayed(Duration(milliseconds: 500));
  return 'Product Data for $productId';
}

void main() {
  final userFuture = fetchUserData('user123');
  final productFuture = fetchProductData('prod456');

  // Create a stream from these two futures
  Stream.fromFutures([userFuture, productFuture]).listen(
    (data) {
      print('Received: $data');
    },
    onDone: () {
      print('All futures completed and stream is done.');
    },
    onError: (e) {
      print('Error: $e');
    }
  );
}

The stream created by Stream.fromFutures will emit "Product Data for prod456" first (because it resolves faster), and then "User Data for user123". This demonstrates that events are emitted as their respective futures complete, not necessarily in the order they were provided in the list.

Real-World Examples in Flutter

1. Fetching Data from a Network with Live Updates

Imagine an app displaying a list of news articles that should refresh automatically.

import 'package:flutter/material.dart';
import 'dart:async';
import 'dart:convert';
import 'package:http/http.dart' as http; // Add http: ^0.13.0 to pubspec.yaml

// Model for a simple Article
class Article {
  final String title;
  final String description;

  Article({required this.title, required this.description});

  factory Article.fromJson(Map<String, dynamic> json) {
    return Article(
      title: json['title'] ?? 'No Title',
      description: json['body'] ?? 'No Description', // Using 'body' for simplicity
    );
  }
}

class NewsService {
  final _articleController = StreamController<List<Article>>.broadcast();
  Stream<List<Article>> get articlesStream => _articleController.stream;

  Timer? _refreshTimer;

  NewsService() {
    _startAutoRefresh();
  }

  Future<void> _fetchArticles() async {
    try {
      final response = await http.get(Uri.parse('https://jsonplaceholder.typicode.com/posts?_limit=5')); // Fake API
      if (response.statusCode == 200) {
        List<dynamic> jsonList = json.decode(response.body);
        List<Article> fetchedArticles = jsonList.map((json) => Article.fromJson(json)).toList();
        _articleController.sink.add(fetchedArticles);
      } else {
        _articleController.sink.addError('Failed to load articles: ${response.statusCode}');
      }
    } catch (e) {
      _articleController.sink.addError('Network Error: $e');
    }
  }

  void _startAutoRefresh() {
    _fetchArticles(); // Fetch immediately
    _refreshTimer = Timer.periodic(Duration(seconds: 10), (timer) {
      print('Auto-refreshing articles...');
      _fetchArticles(); // Fetch every 10 seconds
    });
  }

  void dispose() {
    _refreshTimer?.cancel();
    _articleController.close();
  }
}

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Live News Feed',
      theme: ThemeData(primarySwatch: Colors.deepPurple),
      home: NewsFeedPage(),
    );
  }
}

class NewsFeedPage extends StatefulWidget {
  @override
  _NewsFeedPageState createState() => _NewsFeedPageState();
}

class _NewsFeedPageState extends State<NewsFeedPage> {
  final NewsService _newsService = NewsService();

  @override
  void dispose() {
    _newsService.dispose(); // Important: dispose the service when widget is gone
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Live News Feed')),
      body: StreamBuilder<List<Article>>(
        stream: _newsService.articlesStream,
        builder: (context, snapshot) {
          if (snapshot.connectionState == ConnectionState.waiting) {
            return Center(child: CircularProgressIndicator());
          } else if (snapshot.hasError) {
            return Center(
              child: Padding(
                padding: const EdgeInsets.all(16.0),
                child: Text('Error: ${snapshot.error}', style: TextStyle(color: Colors.red, fontSize: 18)),
              ),
            );
          } else if (snapshot.hasData) {
            final articles = snapshot.data!;
            if (articles.isEmpty) {
              return Center(child: Text('No articles found.'));
            }
            return ListView.builder(
              itemCount: articles.length,
              itemBuilder: (context, index) {
                final article = articles[index];
                return Card(
                  margin: EdgeInsets.all(8.0),
                  elevation: 4.0,
                  child: Padding(
                    padding: const EdgeInsets.all(16.0),
                    child: Column(
                      crossAxisAlignment: CrossAxisAlignment.start,
                      children: [
                        Text(article.title, style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
                        SizedBox(height: 8),
                        Text(article.description, style: TextStyle(fontSize: 14, color: Colors.grey[700])),
                      ],
                    ),
                  ),
                );
              },
            );
          } else {
            return Center(child: Text('Waiting for news...'));
          }
        },
      ),
    );
  }
}

In this code, the NewsService class encapsulates the logic for fetching articles. It uses a StreamController.broadcast() to allow multiple widgets to listen for article updates, even though in this example only the NewsFeedPage does.

The _fetchArticles() method handles the actual HTTP request, while _startAutoRefresh() initiates an immediate fetch and uses a Timer.periodic to trigger new fetches every 10 seconds, adding each new list of articles to _articleController.sink. The dispose() method is essential for cancelling the timer and closing the stream controller to prevent memory leaks.

On the UI side, the NewsFeedPage creates an instance of NewsService, and in its dispose() method, it calls _newsService.dispose() to release resources. A StreamBuilder<List<Article>> listens to _newsService.articlesStream, and its builder function updates the UI dynamically, displaying a loading indicator, an error message, or the list of articles as new events arrive from the stream.

This pattern is a robust way to handle dynamic, asynchronously updating data in your Flutter applications.

2. User Input Handling: Debouncing a Search Field

Imagine a search bar where you don't want to perform a search API call on every keystroke, but rather after the user pauses typing for a short duration (debouncing).

import 'package:flutter/material.dart';
import 'dart:async';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Debounced Search',
      theme: ThemeData(primarySwatch: Colors.green),
      home: DebouncedSearchPage(),
    );
  }
}

class DebouncedSearchPage extends StatefulWidget {
  @override
  _DebouncedSearchPageState createState() => _DebouncedSearchPageState();
}

class _DebouncedSearchPageState extends State<DebouncedSearchPage> {
  final TextEditingController _searchController = TextEditingController();
  final _searchQueryController = StreamController<String>.broadcast();

  String _lastSearchedTerm = '';
  StreamSubscription<String>? _debouncedSubscription;

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

    // Listen to changes in the text field
    _searchController.addListener(() {
      _searchQueryController.sink.add(_searchController.text);
    });

    // Debounce the stream of search queries
    _debouncedSubscription = _searchQueryController.stream
        .distinct() // Only emit if the value is different from the previous
        .debounce(Duration(milliseconds: 500)) // Wait 500ms after the last event
        .listen((query) {
          if (query.isNotEmpty) {
            _performSearch(query);
          } else {
            setState(() {
              _lastSearchedTerm = '';
         });
          }
        });
     }

  void _performSearch(String query) {
    // In a real app, this would be an API call
    print('Performing search for: "$query"');
    setState(() {
      _lastSearchedTerm = query;
    });
  }

  @override
  void dispose() {
    _searchController.dispose();
    _searchQueryController.close();
    _debouncedSubscription?.cancel(); // Cancel the subscription
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Debounced Search')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            TextField(
              controller: _searchController,
              decoration: InputDecoration(
                labelText: 'Search',
                hintText: 'Type to search...',
                prefixIcon: Icon(Icons.search),
                border: OutlineInputBorder(
                  borderRadius: BorderRadius.circular(8.0),
                ),
              ),
              onChanged: (text) {
                // The addListener already handles adding to the stream
                // You could also add directly here if not using addListener
              },
            ),
            SizedBox(height: 20),
            Text(
              _lastSearchedTerm.isEmpty
                  ? 'Start typing to search.'
                  : 'Last performed search: "${_lastSearchedTerm}"',
              style: TextStyle(fontSize: 18),
            ),
            SizedBox(height: 10),
            Text(
              'A search is triggered 500ms after you stop typing.',
              style: TextStyle(fontSize: 14, color: Colors.grey),
            ),
          ],
        ),
      ),
    );
  }
}

// Extension to add a debounce operator to any Stream<T>
extension DebounceExtension<T> on Stream<T> {
  Stream<T> debounce(Duration duration) => transform(
    _DebounceStreamTransformer(duration),
  );
}

// Custom StreamTransformer for debouncing
class _DebounceStreamTransformer<T> extends StreamTransformerBase<T, T> {
  final Duration duration;

  _DebounceStreamTransformer(this.duration);

  @override
  Stream<T> bind(Stream<T> stream) {
    StreamController<T> controller = StreamController<T>();
    Timer? _timer;
    StreamSubscription<T>? _subscription;

    controller.onListen = () {
      _subscription = stream.listen(
        (data) {
          _timer?.cancel(); // Cancel previous timer
          _timer = Timer(duration, () {
            controller.add(data); // Add data after duration
            _timer = null;
          });
        },
        onError: controller.addError,
        onDone: () {
          _timer?.cancel(); // Ensure timer is cancelled if stream done
          controller.close();
        },
      );
    };

    controller.onPause = () => _subscription?.pause();
    controller.onResume = () => _subscription?.resume();
    controller.onCancel = () {
      _timer?.cancel(); // Cancel any pending timer
      return _subscription?.cancel();
    };

    return controller.stream;
  }
}

In this code, the TextEditingController _searchController is a standard Flutter controller that manages the text within a TextField. Alongside it, the StreamController<String> _searchQueryController serves as the source stream for all raw text input changes. It’s a broadcast stream, allowing multiple listeners, such as the debouncing logic, to receive events whenever text input changes.

Every time the user types, _searchController.addListener(() { _searchQueryController.sink.add(_searchController.text); }); adds the latest text value to the _searchQueryController stream. This ensures that every input change emits an event into the stream.

The debouncedSubscription = _searchQueryController.stream ... .listen(...); line contains the main debouncing logic. The .distinct() operator ensures that duplicate inputs (like typing “apple,” deleting it, and retyping “apple”) don’t trigger redundant events. The .debounce(Duration(milliseconds: 500)) operator, implemented as a custom stream transformer, waits for 500 milliseconds of inactivity before emitting the most recent value, resetting its timer with each new event. Once the debounced query is finally emitted, .listen((query) { performSearch(query); }); executes the performSearch method with that query.

The DebounceExtension and _DebounceStreamTransformer make this possible by defining a custom StreamTransformer. The core logic resides in bind(Stream<T> stream), which takes the original stream and produces a transformed one. Inside, a new StreamController is created to manage the output stream, while the input stream is listened to with stream.listen(...).

The debouncing behavior is achieved by canceling any existing timer and starting a new one (timer?.cancel(); timer = Timer(duration, () { ... });). When the timer completes without new events, the data is emitted via controller.add(data). Lifecycle methods like onCancel, onPause, and onResume handle proper cleanup and control, ensuring efficient resource management when listeners are paused, resumed, or canceled.

This debounce pattern is incredibly useful for optimizing expensive operations tied to rapid user input.

Best Practices and Considerations

Keep the following in mind when you’re working with streams:

1. Always close StreamControllers: This is paramount. Forgetting to call _controller.close() (especially in dispose() methods of StatefulWidgets or when a service is no longer needed) leads to memory leaks. If using async*/yield, the stream closes automatically when the generator function finishes.

2. Cancel StreamSubscriptions: If you manually call stream.listen(), remember to store the returned StreamSubscription and call subscription.cancel() when you no longer need to listen. Again, this is typically done in dispose(). StreamBuilder handles its internal subscriptions automatically.

3. Choose the right stream type:

   • Single-Subscription: For one-time data flows, like a file read or a single HTTP response.

   • Broadcast: For multiple UI widgets or logic components needing to react to the same ongoing stream of events. Use StreamController.broadcast().

4. Error handling: Always implement onError callbacks for listen() and handle snapshot.hasError in StreamBuilder to provide a robust user experience.

5. initialData with StreamBuilder: Use initialData when you have a meaningful value to display before the first stream event arrives. This can prevent brief loading indicators if the initial state is known.

6. Avoid excessive StreamBuilder nesting: While convenient, having too many nested StreamBuilders can lead to complex code and potential performance issues if not managed well. Consider consolidating related stream logic.

7. Testing streams: Mock StreamControllers or use Stream.fromIterable to create test streams for your widgets and business logic.

8. Reactive extensions (RxDart): For more advanced stream operations (combining, throttling, buffering, and so on), consider using the rxdart package. It provides a rich set of operators inspired by ReactiveX, making complex asynchronous logic more manageable and declarative.

Advanced Concepts (Brief Introduction)

If you want to go further with streams, there are some key concepts you’ll need to understand. Here’s a brief introduction so you know where to go from here:

1. RxDart: As mentioned, RxDart extends Dart's Stream API with powerful operators. If you find yourself needing more complex stream manipulation than what the core Dart Stream API offers, RxDart is the next logical step. It introduces concepts like BehaviorSubject (a StreamController that remembers the last emitted value and emits it immediately to new listeners) and PublishSubject.

2. BLoC/Cubit pattern: Many popular Flutter state management solutions, like the BLoC (Business Logic Component) pattern, are heavily built on streams. BLoCs expose streams (often using StreamControllers internally) for UI to listen to state changes, completely decoupling presentation from business logic.

3. Stream generators with sync* and yield (for Iterables): While async*/yield create Streams, Dart also has sync*/yield for creating Iterables (synchronous sequences). This is not directly related to asynchronous streams but uses similar syntax.

Conclusion

Streams are a cornerstone of modern asynchronous programming in Flutter. By understanding StreamController, StreamBuilder, StreamSubscription, and the async*/yield syntax, you gain the power to build highly reactive, efficient, and dynamic applications.

From handling network data to real-time user interactions, streams provide a flexible and robust mechanism for managing sequences of asynchronous events. Embrace them, and you'll unlock a new level of responsiveness and elegance in your Flutter development.

References

Official Documentation

1. Dart Streams Tutorial (Official Dart Website): This is the fundamental resource. It covers the core concepts of streams in Dart, including StreamController, listen, async*/yield, and basic transformations.

2. Stream Class API Documentation (Dart): The comprehensive reference for all methods and properties of the Stream class itself. Essential for understanding transformation methods like map, where, take, skip, and so on.

3. StreamController Class API Documentation (Dart): Details on how to create and manage StreamControllers, including single-subscription vs. broadcast.

4. StreamSubscription Class API Documentation (Dart): Information on managing your listeners and cancelling subscriptions.

5. StreamBuilder Widget API Documentation (Flutter): The official Flutter documentation for the StreamBuilder widget, explaining its properties (stream, builder, initialData) and the AsyncSnapshot.

Key Packages

1. async package: Provides utilities for asynchronous programming in Dart, including StreamGroup which is useful for combining multiple streams.

2. rxdart package: Extends Dart's streams with powerful Rx (ReactiveX) operators, making complex asynchronous event handling much easier and more declarative. A must-have for advanced stream usage.

Articles and Tutorials (General)

1. Asynchronous programming: Futures, async, await (Official Dart Guide): While not directly about streams, a solid understanding of Futures is a prerequisite.

Related State Management Patterns

1. BLoC Pattern: Streams are fundamental to the BLoC (Business Logic Component) pattern for state management in Flutter. flutter_bloc package.

2. Bloc Library Documentation

HTTP Package (for Network Examples)

1. http package: For making HTTP requests, as shown in the network example

By exploring these resources, you'll gain an even deeper and more authoritative understanding of streams in the Dart and Flutter ecosystem.

That moment kicked off a massive shift in how healthcare gets delivered.

Telehealth became more than a workaround. It’s now a core part of modern care. As demand grows, developers are stepping up to build secure, real-time platforms that connect patients and providers from anywhere.

In this article, you’ll learn how to build a telehealth application with Stream’s React Video and Chat SDKs. You’ll set up authentication, create video calls, enable messaging, and design a functional user interface that mimics real-world telehealth workflows.

Let’s dive in.

Outline

• Introduction

• Prerequisites

• App Structure

• Project Setup

• Backend Setup

• Frontend Setup

• Stream Chat and Video Integration

• Chat and Video Function (Frontend)

• Project Demo

• Conclusion

Prerequisites

Before you start this tutorial, make sure you have:

• A basic understanding of React.

• Node.js and npm/yarn installed on your computer

• A free account with Stream

• Familiarity with Stream SDKs

• A basic understanding of Tailwind CSS for styling

• Experience with VS Code and Postman (for testing APIs)

App Structure

Before diving into the code, it’s helpful to understand how the app is structured.

# App Flow Structure

- Landing Page  
  - Navigation  
    - Home  
    - About  
    - Sign Up  
      - Verify Account  
        - Log In  
          - Dashboard  
            - Stream Chat  
            - Stream Video  
            - Log Out

Project Setup

Before getting started, create two folders: “Frontend” to handle the client-side code and “Backend” for the server-side logic. This separation allows you to manage both parts of your application efficiently.

Set Up React for the Frontend

Once the folders are created, you can set up the React application in the Frontend folder.

First, navigate to the Frontend directory using the command cd Frontend.

Now you can initialize your React project. You’ll use Vite, a fast build tool for React applications.

To create your React project, run the following command:

npm create vite@latest [project name] -- --template react

Next, navigate to your new project folder, using the command:

cd [project name]

Once there, install the required dependencies by running:

npm install

This command installs both the node_modules folder (which contains all your project's packages) and the package-lock.json file (which records exact versions of installed packages).

Next, you’ll need to install Tailwind CSS for styling. Follow the Tailwind Docs for step-by-step instructions.

Then, it’s time to set up the website. Using React, you’ll create the home sign-in/log-in pages. Both will be nested together using React-router-dom.

Here’s what the home page looks like:

Now, the user has a place to land whenever they visit the website.

Let’s set up the backend.

Backend Setup

Installing Required Packages

Before setting up your project's backend, it's important to define what your project needs to offer. This will help you install all the necessary packages in one go.

Start by moving into the backend folder using the command: cd Backend

Inside the Backend directory, initialize your Node.js project using npm install

This will create a package.json file, which stores metadata and dependencies for your project.

Next, install all the dependencies needed to build your backend. Run the following command:

npm i bcryptjs cookie-parser cors dotenv express jsonwebtoken mongoose nodemailer validator nodemon

Here’s a brief overview of what each package does:

• bcryptjs: Encrypts user passwords for secure storage.

• Cookie-parser: Handles cookies in your application.

• CORS: Middleware that enables cross-origin requests – essential for frontend-backend communication.

• dotenv: Loads environment variables from a .env file into process.env.

• Express: The core framework for building your server and API routes.

• jsonwebtoken: Generates and verifies JWT tokens for authentication.

• Mongoose: Connects your app to a MongoDB database.

• nodemailer: Handles sending emails from your application.

• Validator: Validates user inputs like email, strings, and so on.

• nodemon: Automatically restarts your server when changes are made to files.

Once your packages are installed, create two key files in the backend directory: App.js, which contains your app logic, middleware, and route handlers, and server.js, responsible for initializing and configuring your server.

Next, you have to update your package.json start script. Head to the package.json file in your backend directory and replace the default script:

"scripts": {
    "test": "echo\”Error: no test specified\" && exit 1”
  }

with this:

"scripts": {
    "start": "nodemon server.js"
  }

This setup allows you to run your server using nodemon, automatically reloading it when changes are made. This helps boost productivity during development.

To check if your backend setup is correct, open the server.js file and add a test log: console.log (“Any of your Log Message”). Then, head to your terminal in the backend directory, and run npm start. You should see the log message in the terminal, confirming that your backend is running.

App.js Setup

In the App.js file, start by importing the packages you initially installed.

const express = require("express");

const cors = require("cors");

const cookieParser = require("cookie-parser");

const app = express();


app.use(

  cors({

origin: [

   "http://localhost:5173",

],

credentials: true,

  })

);

app.use(express.json({ limit: "10kb" }));

app.use(cookieParser());

module.exports = app;

Here’s what the code above does:

The require statements import express, cors, and cookie-parser, which are essential for creating your backend server, handling cross-origin requests, and parsing cookies.

The const app = express(); command sets up a new instance of an Express application.

app.use(cors({ origin: ["http://localhost:5173"], credentials: true })); grants permission or allows requests from your frontend and enables cookie sharing between the frontend and backend of your application. This is important for authentication.

The app.use(express.json({ limit: "10kb" })); command is a middleware function that ensures the server can process incoming JSON payloads and protects against overly large requests, which could be used in DoS attacks.

The app.use(cookieParser()); command makes cookies available via req.cookies.

Last, the module.exports = app; command allows the app to be imported in other files, especially in server.js, which is where the app will be started.

Server.js Setup

Once App.js is set up, the next step is to create and configure your server in a new file called server.js.

Before doing that, ensure you have a MongoDB database set up. If you don’t have one yet, you can follow this video tutorial to set up a MongoDB database.

After setting up MongoDB, you will receive a username and password. Copy the password, head to your backend directory, and create a .env file to store it.

After you have stored the password, head back to complete your database setup.

Next, click on the “Create Database User” button, then click on the choose connection method option. Since we are using Node.js for this project, choose the “Drivers” option. This gives you the database connection string (you should see it at No. 3).

Then head to your .env and paste it there, and add auth immediately after you have “.net/”.

Here’s what it looks like:

mongodb+srv://<username>:<password>@cluster0.qrrtmhs.mongodb.net/auth?retryWrites=true&w=majority&appName=Cluster0

Lastly, whitelist your IP address. This ensures your backend can connect to MongoDB from your local machine or any environment during development.

To allow your application to connect to the database:

• Go to the "Network Access" section in the Security sidebar of your MongoDB dashboard.

• Click on “ADD IP ADDRESS.”

• Choose “Allow Access from Anywhere”, then click on Confirm.

At this point, you can set up your server.js

//server.js
require("dotenv").config();
const mongoose = require("mongoose");
const dotenv = require("dotenv"); //to Manage our environment variable

dotenv.config({ path: "./config.env" });
// console.log(process.env.NODE_ENV);

const app = require("./app");

const db = process.env.DB;
//connect the application to database using MongoDB

mongoose
  .connect(db)
  .then(() => {
    console.log("DB connection Successful");
  })
  .catch((err) => {
    console.log(err);
  });

const port = process.env.PORT || 3000;
// console.log(process.env.PORT)

app.listen(port, () => {
  console.log(`App running on port ${port}`);
});

The server.js file is responsible for handling all server-related functions and logic. From the code above, the server.js file loads the environment variables using dotenv, connects your backend to MongoDB using mongoose, and starts the Express server. It gets the database URL and port from the config.env file, connects to the database, then runs your application on the specified port (8000).

If the specified port is not found, it falls back to port 3000 and a confirmation message is printed to the console indicating that the server is up and running on the specified port.

Connect the Database to MongoDB Compass

First, download the MongoDB Compass app. (Go here to download and install: https://www.mongodb.com/try/download/compass). The MongoDB Compass app makes it easy for us to manage our data.

Once the installation is complete, open the app and click on Click to add new connection. Go to your .env file, copy the connection string you initially got when setting up MongoDB, paste it in the URL section, and then click on “connect.” This setup helps you manage your data when you create and delete users.

Set up an Advanced Error Handling Method

You’ll now create an advanced error-handling mechanism. To do so, create a utils folder in your backend, a catchAsync.js file in the utils folder, and add this code:

//catchAsync.js
module.exports = (fn) => {
  return (req, res, next) => {
    fn(req, res, next).catch(next);
  };
};

Next, create an appError.js file still in your utils folder. In the appError.js file, add the following command:

class AppError extends Error {
  constructor(message, statusCode) {
    super(message);

    this.statusCode = statusCode;
    this.status = `${statusCode}`.startsWith("4") ? "fail" : "error";
    this.isOperational = true;

    Error.captureStackTrace(this, this.constructor);
  }
}

module.exports = AppError;

The code above is helpful in tracking and tracing errors. It also provides you with the URL and file location where your error might be occurring, which helps with cleaner error handling and debugging.

Next, let’s create a global error handler. Start by creating a new folder in the backend directory, and name it “controller”. In the controller folder, create your global error handling file. You can name it anything you like. In this example, it’s called globalErrorHandler.js.

Your globalErrorHandler file will define several functions that handle specific error types, such as database issues, validation failures, or even JWT problems and return a nicely formatted error response for users. For the globalErrorHandler to work properly, you have to create a controller function.

So, next, create an errorController.js file (still inside the controller folder). The errorController.js file responds to the user whenever an error is caught, sending the error in JSON format.

globalErrorHandler.js:

// globalErrorHandler.js
const AppError = require("../utils/appError");

const handleCastErrorDB = (err) => {
  const message = `Invalid ${err.path}: ${err.value}.`;
  return new AppError(message, 400);
};

const handleDuplicateFieldsDB = (err) => {
  const value = err.keyValue ? JSON.stringify(err.keyValue) : "duplicate field";
  const message = `Duplicate field value: ${value}. Please use another value!`;
  return new AppError(message, 400);
};

const handleValidationErrorDB = (err) => {
  const errors = Object.values(err.errors).map((el) => el.message);
  const message = `Invalid input: ${errors.join(". ")}`;
  return new AppError(message, 400);
};

const handleJWTError = () =>
  new AppError("Invalid token. Please log in again!", 401);
const handleJWTExpiredError = () =>
  new AppError("Your token has expired! Please log in again.", 401);

module.exports = {
  handleCastErrorDB,
  handleDuplicateFieldsDB,
  handleValidationErrorDB,
  handleJWTError,
  handleJWTExpiredError,
};

Here’s what the code above does:

The const handleCastErrorDB = (err) =>.. section handles MongoDB CastError which usually happens when an invalid ID is passed, and returns a 400 Bad Request error response using your AppError class.

The const handleDuplicateFieldsDB = (err) =>... checks and handles MongoDB duplicate key errors, such as trying to register an email or username that’s already taken and returns a 400 Bad Request error.

The const handleValidationErrorDB = (err) =>... handles Mongoose validation errors (like required fields missing or wrong data types). It gathers all the individual validation error messages and combines them into one.

The const handleJWTError = () => and const handleJWTExpiredError = () => handle errors which might occur as a result of invalid, tampered, or expired JWT tokens and return a 401 Unauthorized error response.

The module.exports = {……}; section exports all the individual error handlers so they can be used in the errorController.js file.

errorController.js:

//errorController.js
const errorHandlers = require("./globalErrorHandler");

const {
  handleCastErrorDB,
  handleDuplicateFieldsDB,
  handleValidationErrorDB,
  handleJWTError,
  handleJWTExpiredError,
} = errorHandlers;

module.exports = (err, req, res, next) => {
  err.statusCode = err.statusCode || 500;
  err.status = err.status || "error";

  let error = { ...err, message: err.message };

  if (err.name === "CastError") error = handleCastErrorDB(err);
  if (err.code === 11000) error = handleDuplicateFieldsDB(err);
  if (err.name === "ValidationError") error = handleValidationErrorDB(err);
  if (err.name === "JsonWebTokenError") error = handleJWTError();
  if (err.name === "TokenExpiredError") error = handleJWTExpiredError();

  res.status(error.statusCode).json({
    status: error.status,
    message: error.message,
    ...(process.env.NODE_ENV === "production" && { error, stack: err.stack }),
  });
};

To ensure your error-handling function works properly, head to your App.js and add the command:

//import command
const globalErrorHandler = require("./controller/errorController");
const AppError = require("./utils/appError");

//Catch unknown routes
app.all("/{*any}", (req, res, next) => {
  next(new AppError(`Can't find ${req.originalUrl} on this server!`, 404)); });

app.use(globalErrorHandler);

This ensures that all errors are properly handled and sends the error response to the user.

Create User Model

To build a user model, create a new folder in the backend directory and name it “model.” Inside the model folder, create a new file named userModel.js.

The userModel.js file is built essentially for user authentication and security. It provides a validation-rich schema for managing users using Mongoose, which maps how user data is structured in the MongoDB database. It includes validations, password hashing, and methods to compare user passwords securely.

//userModel.js
const mongoose = require("mongoose");
const validator = require("validator");
const bcrypt = require("bcryptjs");

const userSchema = new mongoose.Schema(
  {
    username: {type: String, required: [true, "Please provide username"], trim: true, minlength: 3, maxlength: 30, index: true,},
    email: {type: String, required: [true, "Please Provide an email"], unique: true, lowercase: true, validate: [validator.isEmail, "Please provide a valid email"],},
    password: {type: String, required: [true, "Please provide a Password"], minlength: 8, select: false,},
    passwordConfirm: {type: String, required: [true, "Please confirm your Password"],
     validate: {validator: function (el) {return el === this.password;},
        message: "Passwords do not match",
      },
    },
    isVerified: {type: Boolean, default: false,}, otp: String,
    otpExpires: Date,
     resetPasswordOTP: String,
      resetPasswordOTPExpires: Date,
    createdAt: {type: Date, default: Date.now,},}, { timestamps: true });

// Hash password before saving
userSchema.pre("save", async function (next) {
  if (!this.isModified("password")) return next();

  this.password = await bcrypt.hash(this.password, 12);
  this.passwordConfirm = undefined; // Remove passwordConfirm before saving
  next();
});

const User = mongoose.model("User", userSchema);
module.exports = User;

Auth Controller

Now, you can create logic that regulates your user's authentication process. This authentication logic consists of the sign-up, sign-in (log-in), OTP, and so on.

To do so, first head to your controller folder and create a new file. Call it authController.js because it handles the authentication flow of your project.

After you’ve created the file, you’ll create your sign-up function.

//import
const User = require("../model/userModel");
const AppError = require("../utils/appError");
const catchAsync = require("../utils/catchAsync");
const generateOtp = require("../utils/generateOtp");
const jwt = require("jsonwebtoken");
const sendEmail = require("../utils/email")

exports.signup = catchAsync(async (req, res, next) => {
  const { email, password, passwordConfirm, username } = req.body;

  const existingUser = await User.findOne({ email });

  if (existingUser) return next(new AppError("Email already registered", 400));

  const otp = generateOtp();

  const otpExpires = Date.now() + 24 60 60 * 1000; //when thhe otp will expire (1 day)

  const newUser = await User.create({
    username,
    email,
    password,
    passwordConfirm,
    otp,
    otpExpires,
  });

  //configure email sending functionality
  try {
    await sendEmail({
      email: newUser.email,
      subject: "OTP for email Verification",
      html: `<h1>Your OTP is : ${otp}</h1>`,
    });

    createSendToken(newUser, 200, res, "Registration successful");
  } catch (error) {
    console.error("Email send error:", error);
    await User.findByIdAndDelete(newUser.id);
    return next(
      new AppError("There is an error sending the email. Try again", 500)
    );
  }
});

const { email, password, passwordConfirm, username } = req.body; extracts the necessary registration details from the incoming request: email, password, password confirmation, and username during user sign-up.

const existingUser = await User.findOne({ email }); checks the database to see if a user already exists with the given email. If yes, it sends an error response using your AppError utility.

const otp = generateOtp(); generates the OTP, and const otpExpires = Date.now()….. is used to set the OTP to expire at a specified time or day.

With const newUser = await User.create({…});, the new user is saved in MongoDB with their credentials and the OTP info, with the password automatically hashed.

await sendEmail({…}); sends an email to the user. This email contains their sign-in OTP. If the email is sent successfully, createSendToken(newUser, 200, res, "Registration successful"); (which is a utility function) generates a JWT token and sends it in the response with a success message.

If the email fails to send or something goes wrong, await User.findByIdAndDelete(newUser.id); deletes the user from the database to keep things clean, and an error message of There is an error sending the email. Try again", 500 is returned.

Generate OTP

To ensure that your users' OTP is successfully sent to them, in the utils folder, create a new file and name it generateOtp.js. Then add the code:

module.exports = () => {
  return Math.floor(1000 + Math.random() * 9000).toString();
};

The code above is a function that generates a user's random 4-digit OTP and returns it as a string.

After completing the code above, go to your authController.js and ensure you import the generateOtp.js in the import section.

Create User Token

Next, the user sign-in token will be created, and it will be assigned to the user upon sign-in.

const signToken = (userId) => {
  return jwt.sign({ id: userId }, process.env.JWT_SECRET, {
    expiresIn: process.env.JWT_EXPIRES_IN || "90d",
  });
};

//function to create the token
const createSendToken = (user, statusCode, res, message) => {
  const token = signToken(user._id);

  //function to generate the cookie
  const cookieOptions = {
    expires: new Date(
      Date.now() + process.env.JWT_COOKIE_EXPIRES_IN 24 60 60 1000
    ),

    httponly: true,
    secure: process.env.NODE_ENV === "production", //only secure in production
    sameSite: process.env.NODE_ENV === "production" ? "none" : "Lax",
  };

  res.cookie("token", token, cookieOptions);

  user.password = undefined;
  user.passwordConfirm = undefined;
  user.otp = undefined;

Before the code above can work perfectly, create a JWT in your .env file.

//.env
JWT_SECRET = kaklsdolrnnhjfsnlsoijfbwhjsioennbandksd;
JWT_EXPIRES_IN = 90d
JWT_COOKIE_EXPIRES_IN = 90

The code above is how the .env file should look. Your JWT_SECRET can be anything, just as you can see in the code.

Note: The user token creation logic should run before the sign-in logic. So in that case, the signToken and createSendToken logic should be placed at the top before the signup logic.

Send Email

Next, you need to configure your email sending functionality so you can automatically send the user's OTP to their email whenever they sign in. To configure the email, head to the utils folder, create a new file, and give it a name. In this example, the name is email.js.

In email.js, we will send emails using the nodemailer package and Gmail as a provider.

//email.js
const nodemailer = require('nodemailer');

const sendEmail = async (options) => {
  const transporter = nodemailer.createTransport({
    service: 'Gmail',
    auth: {
      user: process.env.HOST_EMAIL,
      pass: process.env.EMAIL_PASS
    }
  })

  //defining email option and structure

  const mailOptions = {
    from: `"{HOST Name}" <{HOST Email} >`,
    to: options.email,
    subject: options.subject,
    html: options.html,
  };
  await transporter.sendMail(mailOptions);
};

module.exports = sendEmail;

From the code above, the const nodemailer = require('nodemailer'); command imports the nodemailer package. This is a popular Node.js library for sending emails.

The const transporter = nodemailer.createTransport({…..}) is an email transporter. Since we will be using the Gmail service provider, service will be assigned to Gmail and auth pulls your Gmail address and password from the .env file where it’s stored.

Note: The password is not your actual Gmail password but rather your Gmail app password. You can see how you can get your Gmail password here.

Once you’ve successfully gotten your Gmail app password, store it in your .env file.

Route Creation

At this point, you have finished setting up your project's signup function. Next, you need to test whether your signup works properly using Postman. But before that, let’s set up and define a route where the signup function will be executed.

To set up your route, create a new folder in your backend directory named "routes" and a file named userRouter.js.

const express = require("express");
const {signup} = require(“../controller/authController”);

const router = express.Router();
router.post("/signup", signup);

module.exports = router;

Next, go to your App.js file and add the router to it.

const userRouter = require("./routes/userRouters"); //Route import statement
app.use("/api/v1/users", userRouter) //common route for all auth, i.e sign up, log in, forget password, etc.

After setting up your routes, you can test your signup to see if it works. This is a post request, and the route URL will be http://localhost:8000/api/v1/users/signup.

The image above shows that the signup function works perfectly with a statusCode of 200 and an OTP code being sent to the user’s email.

Congratulations on reaching this point! You can check your MongoDB database to see if the user is displayed there.

From the image above, you can see that the user details are obtained and the password is in an encrypted form, which ensures the user credentials are safe.

Create a Verify Account Controller Function

In this section, you’ll create a Verify Account controller function. This function verifies a user’s account using the OTP code sent to their email address.

First, go to your authController.js file and add:

exports.verifyAccount = catchAsync(async (req, res, next) => {
  const { email, otp } = req.body;

  if (!email || !otp) {
    return next(new AppError("Email and OTP are required", 400));
  }

  const user = await User.findOne({ email });

  if (!user) {
    return next(new AppError("No user found with this email", 404));
  }

  if (user.otp !== otp) {
    return next(new AppError("Invalid OTP", 400));
  }

  if (Date.now() > user.otpExpires) {
    return next(
      new AppError("OTP has expired. Please request a new OTP.", 400)
    );
  }

  user.isVerified = true;
  user.otp = undefined;
  user.otpExpires = undefined;

  await user.save({ validateBeforeSave: false });

  // ✅ Optionally return a response without logging in
  res.status(200).json({
    status: "success",
    message: "Email has been verified",
  });
});

Next, create a middleware function to authenticate the currently logged-in user.

In your backend directory, create a new folder called middlewares. Inside the middlewares folder, create a file named isAuthenticated.js.

Add the following code:

//isAuthenticated.js
const jwt = require("jsonwebtoken");
const catchAsync = require("../utils/catchAsync");
const AppError = require("../utils/appError");
const User = require("../model/userModel");

const isAuthenticated = catchAsync(async (req, res, next) => {
  let token;

  // 1. Retrieve token from cookies or Authorization header
  if (req.cookies?.token) {
    token = req.cookies.token;
  } else if (req.headers.authorization?.startsWith("Bearer")) {
    token = req.headers.authorization.split(" ")[1];
  }

  if (!token) {
    return next(
      new AppError(
        "You are not logged in. Please log in to access this resource.",
        401
      )
    );
  }

  // 2. Verify token
  let decoded;
  try {
    decoded = jwt.verify(token, process.env.JWT_SECRET);
  } catch (err) {
    return next(
      new AppError("Invalid or expired token. Please log in again.", 401)
    );
  }

// 3. Confirm user still exists in database
  const currentUser = await User.findById(decoded._id);
  if (!currentUser) {
    return next(
      new AppError("User linked to this token no longer exists.", 401)
    );
  }

  // 4. Attach user info to request
  req.user = currentUser;
  req.user = {
    id: currentUser.id,
    name: currentUser.name,
  };

  next();
});

module.exports = isAuthenticated;
```
Now, go to your `userRouter.js` file and add the route for the verify account function:
```
const { verifyAccount} = require("../controller/authController");
const isAuthenticated = require("../middlewares/isAuthenticated");
router.post("/verify", isAuthenticated, verifyAccount);

Here is what these two sets of code are doing:

When a user sends a request to the /verify route, the isAuthenticated middleware runs first. It checks whether a valid token exists in the cookie or authorization header. If no token is found, it throws an error: You are not logged in. Please log in to access this resource.

If a token is found, it verifies the token and checks if the associated user still exists. If not, another error is thrown: "User linked to this token no longer exists."

If the user exists and the token is valid, their details are attached to the request (req.user). The request then proceeds to the verifyAccount controller, which handles OTP verification.

You can test this endpoint using Postman with a POST request to: http://localhost:8000/api/v1/users/verify

The image above shows that the verify token function is working well, and a status code of 200 is displayed.

Login Function

If you’ve reached this point, you’ve successfully signed up and verified a user’s account.

Now it’s time to create the login function, which allows a verified user to access their account. Here’s how you can do that:

Go to your authController.js file and create your login function by adding the following:

exports.login = catchAsync(async (req, res, next) => {
  const { email, password } = req.body;

  // 1. Validate email & password presence
  if (!email || !password) {
    return next(new AppError("Please provide email and password", 400));
  }

  // 2. Check if user exists and include password
  const user = await User.findOne({ email }).select("+password");
  if (!user || !(await user.correctPassword(password, user.password))) {
    return next(new AppError("Incorrect email or password", 401));
  }

  // 3. Create JWT token
  const token = signToken(user._id);

  // 4. Configure cookie options
  const cookieOptions = {
    expires: new Date(
      Date.now() +
        (parseInt(process.env.JWT_COOKIE_EXPIRES_IN, 10) || 90) 24 60 60 1000
    ),
    httpOnly: true,
    // secure: process.env.NODE_ENV === "production",
    // sameSite: process.env.NODE_ENV === "production" ?
    //  "None" : "Lax",

    //set to false during or for local HTTP and cross-origin
    secure: false,
    sameSite: "Lax",
  };

  // 5. Send cookie
  res.cookie("token", token, cookieOptions);

});

if (!email || !password) {…} checks if the user actually provided both an email and a password. If not, it returns the error: Please provide email and password", 400.

const user = await User.findOne({ email }).select("+password"); searches the database for a user with the provided email and explicitly includes the password field, since it’s normally hidden by default in the schema.

if (!user || !(await user.correctPassword(…))) {…} checks if the user exists and if the password entered matches the one stored in the database (after hashing comparison). If either is wrong, it throws: Incorrect email or password.

The line signToken(user._id) generates a JWT using the user's unique ID. The cookieOptions object configures how the cookie behaves – it sets the cookie to expire after a specific number of days defined in the .env file, marks it as httpOnly to prevent JavaScript access for security, sets secure to false since the app is currently in development, and uses sameSite: "Lax" to allow cross-origin requests during local testing.

Finally, res.cookie(...) sends the token as a cookie attached to the HTTP response, enabling the client to store the token for authentication purposes.

From the code above, you may have noticed that the password stored in the database is hashed for security reasons. This means it looks completely different from the user's password when logging in. So, even if a user types in the correct password, it won't match the stored hash directly through a simple comparison.

To fix this, you need to compare the entered password with the hashed one using the bcryptjs package.

Head over to your userModel.js file and create a method that handles password comparison. This method will take the plain text password provided by the user and compare it to the hashed password stored in the database.

//userModel.js
//create a method responsible for comparing the password stored in the database

userSchema.methods.correctPassword = async function (password, userPassword) {
  return await bcrypt.compare(password, userPassword);
};

This correctPassword method uses bcrypt.compare(), which internally hashes the plain password and checks if it matches the stored hashed version. This ensures that login validation works correctly and securely, even though the actual password is not stored in plain text.

Next, add the Login functionality to the userRouter.js file.

const {login} = require("../controller/authController");
const isAuthenticated = require("../middlewares/isAuthenticated");

router.post("/login", login);

You can test this endpoint using Postman with a POST request to: http://localhost:8000/api/v1/users/login

Logout Function

At this point, you can implement the logout function to end a user's session securely. To do this, navigate to your authController.js file and add the following function:

//creating a log out function
exports.logout = catchAsync(async (req, res, next) => {
  res.cookie("token", "loggedout", {
    expires: new Date(0),
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
  });

  res.status(200).json({
    status: "success",
    message: "Logged out successfully",
  });
});

This function works by overwriting the authentication cookie named token with the value "loggedout" and setting its expiration time to the past using new Date(0). This effectively invalidates the cookie and removes it from the browser.

The httpOnly: true flag ensures that the cookie cannot be accessed via JavaScript, which protects it from XSS attacks, while the secure flag ensures that the cookie is only sent over HTTPS in a production environment. Once the cookie is cleared, a success response is returned with the message "Logged out successfully" to confirm the action.

Next, add the logout functionality to your route:

const {logout} = require("../controller/authController");
const isAuthenticated = require("../middlewares/isAuthenticated");

router.post("/logout", logout);

Then, head to Postman to test your logout function and see if it works.

Frontend Setup

Now that your backend is up and running, you can integrate it into your frontend application.

First, navigate to the frontend directory using the command cd Frontend.

Create a new folder in the src folder where your authentication-related files will live. Depending on your preference or app structure, you can name it something like auth or pages. Then, create a new file called NewUser. js. This file will handle user signup functionality.

import axios from 'axios';
import React, { useState } from 'react';
import { Link, useNavigate } from 'react-router-dom';
import { Loader } from 'lucide-react';
import { useDispatch } from 'react-redux';
import { setAuthUser, setPendingEmail } from '../../../../store/authSlice';

const API_URL = import.meta.env.VITE_API_URL;

function NewUser() {
  const dispatch = useDispatch();
  const navigate = useNavigate();

  const [loading, setLoading] = useState(false);

  const [formData, setFormData] = useState({
    username: '',
    email: '',
    password: '',
    passwordConfirm: '',
  });

  const handleChange = (e) => {
    const { name, value } = e.target;
    setFormData((prev) => ({ ...prev, [name]: value }));
  };

  const submitHandler = async (e) => {
    e.preventDefault();
    setLoading(true);
    try {
      const response = await axios.post(`${API_URL}/users/signup`, formData, {
        withCredentials: true,
      });
      const user = response.data.data.user;
      dispatch(setAuthUser(user));
      dispatch(setPendingEmail(formData.email)); // Save email for OTP
      navigate('/verifyAcct'); // Navigate to OTP verification page
    } catch (error) {
      alert(error.response?.data?.message || 'Signup failed');
    } finally {
      setLoading(false);
    }
  };

  return (
<div>
// visit the frontend Github repository to see the remaining code for the OTP Verification

https://github.com/Derekvibe/Telehealth_Frontend/blob/main/src/pages/Auth/Join/NewUser.jsx
    </div>
  );
}

export default NewUser;

The code above renders a signup form with fields for username, email, password and passwordConfirm. When the user submits the form, the frontend sends a POST request to the backend’s /users/signup endpoint using Axios. The withCredentials: true option ensures cookies like the auth token are properly set by the backend.

If the signup is successful, the user data is dispatched into Redux using setAuthUser(), and their email is saved with setPendingEmail() so it can be used during OTP verification. Then, the user is redirected to the /verifyAcct route, where they can enter their OTP.

OTP Verification Page

The OTP verification page is the next step in the user authentication process. Once a user signs up, they are redirected to enter the 4-digit OTP sent to their email. This verifies their account before allowing login access.

import React, { useState, useRef, useEffect } from 'react';
import { useSelector, useDispatch } from 'react-redux';
import { useNavigate, Link } from 'react-router-dom';
import axios from 'axios';
import { clearPendingEmail } from '../../../../store/authSlice';

const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:5000/api'; // adjust as needed

function VerifyAcct() {
  const [code, setCode] = useState(['', '', '', '']);
  const [loading, setLoading] = useState(false);
  const [resendLoading, setResendLoading] = useState(false);
  const [timer, setTimer] = useState(60);

  const inputsRef = useRef([]);
  const dispatch = useDispatch();
  const navigate = useNavigate();
  const email = useSelector((state) => state.auth.pendingEmail);

  useEffect(() => {
    let interval;
    if (timer > 0) {
      interval = setInterval(() => setTimer((prev) => prev - 1), 1000);
    }
    return () => clearInterval(interval);
  }, [timer]);

  const handleChange = (value, index) => {
    if (!/^\d*$/.test(value)) return;
    const newCode = [...code];
// visit the frontend Github repository to see the remaining code for the OTP Verification
https://github.com/Derekvibe/Telehealth_Frontend/blob/main/src/pages/Auth/login/VerifyAcct.jsx
}
export default VerifyAcct;

Here’s what the code does:

The OTP is stored as an array of 4 characters ([‘ ‘, ‘ ‘, ‘ ‘, ‘ ‘]). Each box only accepts digits, and focus automatically moves to the next input as the user types in the digit. The focus returns to the previous input box if the user presses the backspace button on an empty box.

When the OTP has been added and the form is submitted, the 4-digit code is joined into a string and an HTTP POST request is made to the backend /user/verify/ endpoint along with the stored email and OTP. If the verification is successful, the user is alerted and redirected to the login page, and if not, an error is shown.

Log In

Now you can create the login interface for your application. First, create a Login.jsx file and input the code:

//Login.Jsx

import React, { useState } from 'react';
import { Link, useNavigate } from 'react-router-dom';
import axios from 'axios';

const API_URL = import.meta.env.VITE_API_URL || 'https://telehealth-backend-2m1f.onrender.com/api/v1';

function Join() {
  const [formData, setFormData] = useState({ email: '', password: '' });
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');
  const navigate = useNavigate();

  const handleChange = (e) => {
    setFormData({ ...formData, [e.target.name]: e.target.value });
  };

  const handleLogin = async (e) => {
    e.preventDefault();
    setLoading(true);
    setError('');

    try {
      const res = await axios.post(`${API_URL}/users/login`, formData, {
        withCredentials: true,
      });

      if (res.data.status === 'success') {
        const { token, user, streamToken } = res.data;

        // Save to localStorage
        localStorage.setItem('authToken', token);
        localStorage.setItem('user', JSON.stringify(user));
        localStorage.setItem('streamToken', streamToken);

        navigate('/dashboard');
      }
    } catch (err) {
      console.error(err);
      setError(
        err.response?.data?.message || 'Something went wrong. Please try again.'
      );
    } finally {
      setLoading(false);
    }
  };

  return (
<div>
{// visit the frontend Github repository to see the remaining code for the OTP Verification
https://github.com/Derekvibe/Telehealth_Frontend/blob/main/src/pages/Auth/login/Login.jsx
 </div>
);
}

The Export default Join; component allows a registered and verified user to log into your application using their email and password. It handles form submission, talks to the backend, and securely stores user data if login is successful.

handleChange() updates the email or password field as the user types.

handleLogin() is triggered when the login form is submitted. When the login button is triggered, it sends a Post request to /users/login with the form data, which includes {withCredentials: true} to enable cookie handling.

If login is successful, it extracts the JWT token, user data, and Stream Chat token from the response and stores them in the localStorage so the user stays logged in across sessions. Then it redirects the user to the dashboard page using navigate(‘/dashboard’).

Set Up the Frontend Route

Just as you set up the backend route, you have to do the same for the frontend.

Head to App.jsx. Before adding the route, make sure you have installed the react-router-dom package. If not, run this command in the frontend terminal:

npm install react-router-dom

Then, add the command to your App.jsx file:

import React from 'react';
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import HomeIndex from './pages/Home/HomeIndex';
import Hero from './pages/Home/Hero';

//Authentication Section
import NewUser from './pages/Auth/Join/NewUser';
import Login from './pages/Auth/login/Login'
import VerifyAcct from './pages/Auth/login/VerifyAcct';

// Dashboard
import Dashboard from './pages/Dashboard/Dashboard';
import VideoStream from './components/VideoStream';

const router = createBrowserRouter([
  {
    path: '/',
    element: <HomeIndex />,
    children: [
      { index: true, element: <Hero /> }
    ],
  },

  {
    path: 'signup',
    element: <NewUser />,
    children: [
      { index: true, element: <NewUser /> }
    ],
  },

  {
    path: 'login',
    element: <Login />,
    children: [
      {index:true, element:<Login />}
    ]
  },

]);
{// visit the frontend Github repository to see the remaining code for the OTP Verification
https://github.com/Derekvibe/Telehealth_Frontend/blob/main/src/App.jsx}

function App() {
  return (
    <div className='border border-red-700 w-full min-w-[100vw] min-h-[100vh]'>
      <RouterProvider router={router} />
    </div>
  );
}

export default App;

Stream Chat and Video Integration

Before proceeding to the dashboard, let’s integrate the Stream Chat and Video functionality into the project.

First, create a free Stream account, start a new project in your dashboard, and get your APP KEY and API_SECRET.

STREAM_API_KEY=your_app_key
STREAM_API_SECRET=your_api_secret

Watch the Stream Chat React Quick Start Guide to see how you can set it up.

Next, store your Stream APP KEY and API_SECRET in your .env.

Install Stream Packages (Frontend)

Now, install the Stream Chat and Video packages in your terminal.

npm install stream-chat stream-chat-react
npm install @stream-io/video-react-sdk
npm install @stream-io/stream-chat-css

Stream Token Handler

First, create a new file in your frontend Src directory and name it. In this example, it’s StreamContext.jsx. This file sets up a context to fetch and manage the Stream Chat token on login and includes logout functionality.

import React, { createContext, useContext, useEffect, useState } from "react";
import axios from "axios";

const API_URL = import.meta.env.VITE_API_URL || 'https://telehealth-backend-2m1f.onrender.com/api/v1';

// 1. Create the context
const StreamContext = createContext();

// 2. Provider component
export const StreamProvider = ({ children }) => {
  const [user, setUser] = useState(null);
  const [token, setToken] = useState(null);

  useEffect(() => {
    const fetchToken = async () => {
      try {
        const res = await axios.get(`${API_URL}/stream/get-token`, {
          withCredentials: true,
        });

        if (res.data?.user && res.data?.token) {
          setUser(res.data.user);
          setToken(res.data.token);
          console.log("Stream user/token:", res.data);
        } else {
          console.error("Token or user missing in response:", res.data);
        }
      } catch (error) {
        console.error("Error fetching Stream token:", error);
      }
    };

    fetchToken();
  }, []);

  //Log out Functionality
  const logout = async () => {
    try {
      await axios.post(`${API_URL}/users/logout`, {},
        {
          withCredentials: true
        });

      // Clear localStorage
      localStorage.removeItem('authToken');
      localStorage.removeItem('user');
      localStorage.removeItem('streamToken');

      // Clear context
      setUser(null);
      setToken(null);
    } catch (error) {
      console.error("Logout failed", error);
    }
  };

  // Expose Logout with capital L
  return (
    <StreamContext.Provider value={{ user, token, Logout:logout }}>
      {children}
    </StreamContext.Provider>
  );
};

// 3. Custom hook for easy access
export const useStream = () => useContext(StreamContext);

The code above creates a StreamContext using React’s Context API. In the useEffect section, it makes a GET request to /stream/get-token to fetch the authenticated user and their Stream token. Then it stores them in user and token states. It also provides the user/token through the context so that any component that needs it can make use of it.

Finally, it adds a Logout method that hits the logout endpoint and clears all stored auth data from localStorage.

Next, open your main.jsx and wrap your entire application with the StreamProvider so all child components can access the Stream context.

// main.jsx
import { createRoot } from 'react-dom/client';
import { StrictMode } from 'react';
import App from './App';
import { StreamProvider } from './components/StreamContext';

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <StreamProvider>
      <App />
    </StreamProvider>
  </StrictMode>
);

Set Up Stream API

After successfully creating the streamContent, the next step is to set up the Stream API. This will be the endpoint from which the user ID and user Stream token can be generated and fetched during login.

To set it up, navigate to your backend directory by running cd Backend in your terminal. Then install the Stream package using the command:

npm install getstream
npm install stream-chat stream-chat-react

Open your .env file and add your Stream API KEY and API_SECRET:

STREAM_API_KEY=your_app_key
STREAM_API_SECRET=your_api_secret

Next, open your authController.js and create your Stream Chat logic:

//Initialize the Stream Client
const {StreamChat} = require("stream-chat");
const streamClient = StreamChat.getInstance(
  process.env.STREAM_API_KEY,
  process.env.STREAM_API_SECRET
);

// Modifies the `createSendToken to include `streamToken`
const createSendToken = (user, statusCode, res, message) => {
……
const streamToken = streamClient.createToken(user._id.toString());

  //structure of the cookie response when sent to the user
  res.status(statusCode).json({
    status: "success",
    message,
    token,
    streamToken,
    data: {
      user: {
        id: user._id.toString(),
        name: user.username,
      },
    },
  });
};

//login functionality
exports.login = catchAsync(async (req, res, next) => {
 {…………………..}

// Generate Stream token
  await streamClient.upsertUser({
    id: user._id.toString(),
    name: user.username,
  });
  const streamToken = streamClient.createToken(user._id.toString());

user.password = undefined;

  res.status(200).json({
    status: "success",
    message: "Login successful",
    token,
    user: {
      id: user._id.toString(),
      name: user.username,
    },
    streamToken,
  });

streamRoutes Endpoint

Next, create an endpoint from which the Stream token can be called. To do this, go to your routes folder and create a new file called streamRoutes.js. In streamRoutes.js, add the command:

const express = require("express");
const { StreamChat } = require("stream-chat");

const protect = require("../middlewares/protect");

const router = express.Router();

const apiKey = process.env.STREAM_API_KEY;
const apiSecret = process.env.STREAM_API_SECRET;

if (!apiKey || !apiSecret) {
  throw new Error(
    "Missing Stream credentials. Check your environment variables."
  );
}

const streamClient = StreamChat.getInstance(apiKey, apiSecret);

router.get("/get-token", protect, async (req, res) => {
  try {
    const { id, username } = req.user || {};
    console.log(req.user.id, "User");
    // TRY LOGGING THE ID AND NAME FROM YOUR REQUEST FIRST

    if (!id || !username) {
      return res.status(400).json({ error: "Invalid user data" });
    }

    // const userId = _id.toString();
    const user = { id, username };

    // Ensure user exists in Stream backend
    await streamClient.upsertUser(user);

    // Add user to my_general_chat channel
    const channel = streamClient.channel("messaging", "my_general_chat");
    await channel.addMembers([id]);


    // Generate token
    const token = streamClient.createToken(id);
    res.status(200).json({ token, user });
  } catch (error) {
    console.error("Stream token generation error:", error);
    res.status(500).json({ error: "Failed to generate Stream token" });
  }
});

/**
 * @route   POST /api/stream/token
 * @desc    Generate a Stream token for any userId from request body (no auth)
 * @access  Public
 */
router.post("/token", async (req, res) => {
  try {
    const { userId, name } = req.body;

    if (!userId) {
      return res.status(400).json({ error: "userId is required" });
    }

    const userName = name || "Anonymous";
    const user = { id: userId, name: userName };

    await streamClient.upsertUser(user);

    // Add user to my_general_chat channel
    const channel = streamClient.channel("messaging", "my_general_chat");
    await channel.addMembers([userId]);


    const token = streamClient.createToken(userId);

    res.status(200).json({
      token,
      user: {
        id: userId,
        name: name,
        role: "admin",
        image: `https://getstream.io/random_png/?name=${name}`,
      },
    });
  } catch (error) {
    console.error("Public token generation error:", error);
    res.status(500).json({ error: "Failed to generate token" });
  }
});

module.exports = router;

User Logout Endpoint

Go to your authController.js and create a functionality that handles logging out the user:

exports.logout = catchAsync(async (req, res, next) => {
  res.cookie("token", "loggedout", {
    expires: new Date(0),
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
  });

  res.status(200).json({
    status: "success",
    message: "Logged out successfully",
  });
});

Then register your logout route to your userRouters.js:

const express = require("express");
const {logout}= require("../controller/authController");
const isAuthenticated = require("../middlewares/isAuthenticated");


router.post("/logout", isAuthenticated, logout);

module.exports = router;

Chat and Video Function (Frontend)

After setting up your backend Stream API, the last task is setting up chat and video in your frontend application.

Dashboard.jsx

Create a new file Dashboard.jsx in your frontend directory. This is where you will set up your Stream and video function.

import React, { useState, useEffect } from "react";
import axios from "axios";
import {
  Chat,
  Channel,
  ChannelHeader,
  MessageInput,
  MessageList,
  Thread,
  Window,
  useCreateChatClient,
} from "stream-chat-react";
import "stream-chat-react/dist/css/v2/index.css";
import { useStream } from "../../components/StreamContext";
import VideoStream from "../../components/VideoStream";
import { useNavigate } from "react-router-dom";



const apiKey = import.meta.env.VITE_STREAM_API_KEY;

const API_URL = import.meta.env.VITE_API_URL || 'https://telehealth-backend-2m1f.onrender.com/api/v1';

function App() {
  const [channel, setChannel] = useState(null);
  const [clientReady, setClientReady] = useState(false);
  const navigate = useNavigate();

  // const ChatComponent = () => {
    const { user, token, Logout } = useStream();

    // Always call the hook
    const chatClient = useCreateChatClient({
      apiKey,
      tokenOrProvider: token,
      userData: user?.id ? { id: user.id } : undefined,
    });

  // Debug: See when user/token is ready
  useEffect(() => {
    console.log("Stream user:", user);
    console.log("Stream token:", token);
  }, [user, token]);

    // Connect user to Stream
    useEffect(() => {
      const connectUser = async () => {
        if (!chatClient || !user || !token || !user?.id) {
          console.warn("Missing chat setup data:", { chatClient, token, user });
          return;
        }


        try {
          await chatClient.connectUser(
            {
              id: user.id,
              name: user.name || "Anonymous",
              image:
                user.image ||
                `https://getstream.io/random_png/?name=${user.name || "user"}`,
            },
            token
          );

          const newChannel = chatClient.channel("messaging", "my_general_chat", {
            name: "General Chat",
            members: [user.id],
          });

          await newChannel.watch();
          setChannel(newChannel);
          setClientReady(true);
        } catch (err) {
          console.error("Error connecting user:", err);
        }
      };

      connectUser();
    }, [chatClient, user, token]);

    const handleVideoCallClick = () => {
      navigate("/videoCall");
  };

  const handleLogout = async () => {
    await Logout();
    navigate("/login");
  }

  if (!user || !token) {
    return <div className="text-red-600">User or token not ready.</div>;
  }

  if (!clientReady || !channel) return <div>Loading chat...</div>;


  return (
{ checkout the github repo}
            <ChannelHeader />
            <MessageList />
            <MessageInput />
          </Window>
          <Thread />
        </Channel>
      </Chat>


      </div>

    );
  }

export default App;

Video Setup

You’ll now set up the video function for your frontend. To do so, create a new file VideoStream.jsx and add the command:

import React, { useEffect, useState } from "react";
import { StreamVideoClient } from "@stream-io/video-client";
import { StreamVideo, StreamCall } from "@stream-io/video-react-sdk";
import { useNavigate } from "react-router-dom";


import { useStream } from "./StreamContext";
import { MyUILayout } from "./MyUILayout";


const apiKey = import.meta.env.VITE_STREAM_API_KEY;

function VideoStream() {

  const [client, setClient] = useState(null);
    const [call, setCall] = useState(null);
  const { user, token } = useStream();
  const navigate = useNavigate();

  useEffect(() => {

    let clientInstance;
    let callInstance;


    const setup = async () => {
      if (!apiKey || !user || !token) return;

      clientInstance = new StreamVideoClient({ apiKey, user, token });

      callInstance = clientInstance.call("default", user.id); // Use user.id as callId


      await callInstance.join({ create: true });

      setClient(clientInstance);
      setCall(callInstance);
    };

    setup();

    return () => {
      if (callInstance) callInstance.leave();
      if (clientInstance) clientInstance.disconnectUser();

    };
  }, [user, token]);

  const handleLeaveCall = async () => {
    if (call) await call.leave();
    if (client) await client.disconnectUser();

    setCall(null);
    setClient(null);

    navigate("/dashboard"); // or any other route
  };

  if (!apiKey) return <div>Missing Stream API Key</div>;

  if (!client || !call)
    return (
  <div className="flex items-center justify-center h-screen text-xl font-semibold">
    Connecting to the video call...
  </div>
    );

  return (
    <div className="relative h-screen w-full p-2 sm:p-4 bg-gray-50">
      <StreamVideo client={client}>
        <StreamCall call={call}>
          <MyUILayout />
        </StreamCall>
      </StreamVideo>

      <button
        onClick={handleLeaveCall}
        className="absolute top-2 right-2 sm:top-4 sm:right-4 bg-red-600 text-white text-sm sm:text-base px-3 sm:px-4 py-1.5 sm:py-2 rounded-lg shadow hover:bg-red-700 transition"
      >
        Leave Call
      </button>
    </div>
    );
  }

export default VideoStream;

//MYUILayout.jsx
import React from 'react';
import {
  useCall,
  useCallStateHooks,
  CallingState,
} from '@stream-io/video-react-sdk';

export function MyUILayout() {
  const call = useCall();
  const { useCallCallingState, useParticipantCount } = useCallStateHooks();
  const callingState = useCallCallingState();
  const participantCount = useParticipantCount();

  if (callingState !== CallingState.JOINED) {
    return <div>Joining call...</div>;
  }

  return (
    <div style={{ padding: '1rem', fontSize: '1.2rem' }}>
      ✅ Call "<strong>{call?.id}</strong>" has <strong>{participantCount}</strong> participants.
    </div>
  );
}

Project Demo

Congratulations! You have successfully integrated Stream’s chat and video function into your application.

Conclusion

And that’s a wrap!

You’ve built a telehealth app with secure video, real-time chat, and user authentication – all powered by Stream’s Chat and Video SDKs.

This foundation gives you the flexibility to expand further with features like appointment scheduling, patient history, or HIPPA-compliant file sharing.

You can find the frontend and backend applications on GitHub. The frontend app is hosted using the Vercel hosting service, and the backend is hosted on Render.

Check out the repository of the application.

Happy coding! 🚀