Forem: Elys Maldov

A low-cost idea to automate your e-commerce platform with Payload CMS and Hermes Agent

Elys Maldov — Thu, 19 Mar 2026 16:50:35 +0000

A few days ago, I saw this tweet on Indonesian X about how sellers are moving to their own marketplace platforms due to increasing e-commerce platform fees:

// Detect dark theme var iframe = document.getElementById('tweet-2033512460813312279-794'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2033512460813312279&theme=dark" }

I remembered a few months ago Payload CMS finally released an update to their e-commerce template. After trying it out, it gives you a really good setup for a basic e-commerce with auth, inventory management, cart, and even payment flow using Stripe (with an option to create integrate your own payment method). It even has marketing features such as SEO and page builder, and of course you can customize Payload CMS in any way you want even white-labelling it to use with multiple clients easily.

In other news, Hermes Agent has been trending recently on the AI space due to it being a "better" version of OpenClaw. After giving Hermes Agent a spin, I got to say it's very capable, easier to setup, and runs better than OpenClaw! I really appreciate how easy it is to setup the agent with your WhatsApp/Telegram and use it like you would message your personal assistant. It also has a lot of built-in tools to do business stuff like analyzing data, drafting emails, and any task you can automate. It even has memory so it remembers who you are better the more you use it.

Considering how much AI agents and LLMs have grown to help automating our tasks and making building products quicker, it wouldn't be crazy to try to build your own e-commerce platform and integrate an actual ai assistant that helps you automate operations so you can focus on important business stuff. In this article, I'll walk you through how to use Payload CMS to build a low-cost e-commerce platform and powering it with Hermes Agent to automatically assist in managing your platform.

What we'll do

We'll setup a basic e-commerce platform complete with auth, inventory management, cart, payment, SEO, and page builder. We won't have to code much since we can just use Payload CMS with its e-commerce template, which basically provides all of those out-of-the-box. Next, we'll setup Hermes Agent locally and connect it to our Payload CMS e-commerce platform using MCP. In the end, we'll have a basic e-commerce platform and an agent we can talk to help manage our platform such as updating the inventory, analyzing user's carts, and even creating blog posts for marketing.

You can clone this project's repo here: ElysMaldov/payload-hermes-ecommerce

Setup Payload CMS with e-commerce template

Make sure you've setup your environment to install Payload CMS, then follow the e-commerce template quickstart. For this tutorial, we'll be using SQLite for the database, but you can use any DB you want.

Once finished, you can run the program with pnpm dev. I won't go into details about how Payload CMS nor this template works, but just know now we have 2 apps in this 1 project that you can customize however you want:

The client facing e-commerce platform in localhost:3000:

And the admin dashboard in localhost:3000/admin:

Exploring Payload CMS E-commerce

On the first run, follow the instructions to open the admin dashboard, create your first admin account, seed the database, and go try out the features Payload provides. Optionally, you can create a Stripe account and give it your sandbox mode API key to try out the payment flow. For my Indonesian fellows, you can create custom Payment methods for Xendit, Midtrans, and any other gateways by following this tutorial: Payment Adapters | Documentation | Payload.

When your database is seeded, you should now able to see the client e-commerce app is updated with new pages, mainly the Shop page:

You can manage your inventory in the admin dashboard by opening the Products collection:

As a customer, you can add items to cart, pick product variants, and pay it on the checkout page. As an admin, you can manage all of these data in the admin dashboard. It's really comprehensive for a e-commerce starter, but the template lacks shipping and activity logs, which you can add your own later.

Setting up Hermes Agent

Follow the docs to install your Hermes Agent. For this tutorial, I'll be using Nous Portal provider, WSL2, and Telegram Bot to communicate with the agent. I created a new WSL2 instance just for this tutorial with this command: wsl --install Ubuntu --name PayloadHermesEcommerce, this prevents the agent from messing with my other existing WSLs. We can assume the agent is working if you can chat with it through the messaging gateway you setup (for me it's Telegram).

Integrating Hermes with Payload using MCP plugin

Currently, our Hermes Agent can't really communicate with our Payload app. Sure, we could prompt it to learn our Payload app's API endpoints and make skills/tools for it, but a much more organized way is using MCP. We first need to setup Payload MCP Plugin, this gives us an organized method to control what our agent can access on our Payload app. Once the MCP server is setup, you can enable/disable which collections and other data your agent can utilize through the MCP. For this tutorial, I enable all the e-commerce collections.

 mcpPlugin({
    collections: {
      addresses: {
        enabled: true,
      },
      carts: {
        enabled: true,
      },
      categories: {
        enabled: true,
      },
      forms: {
        enabled: true,
      },
      media: {
        enabled: true,
      },
      orders: {
        enabled: true,
      },
      pages: {
        enabled: true,
      },
      products: {
        enabled: true,
      },
      transactions: {
        enabled: true,
      },
      users: {
        enabled: true,
      },
      variantOptions: {
        enabled: true,
      },
      variants: {
        enabled: true,
      },
      variantTypes: {
        enabled: true,
      },
      'form-submissions': {
        enabled: true,
      },
    },
  })

Next, you need to configure the MCP client in Hermes Agent config. Open your .hermes/config.yaml and add this section:

mcp_servers:
  PayloadHermesEcommerce:
    type: "http"
    url: "http://windows.local:3000/api/mcp"
    headers:
      Authorization: "Bearer API-KEY-HERE"

Replace your API-KEY-HERE with the API key you get from Payload CMS API Keys collection in the admin dashboard that was created from the MCP plugin.

Sidenote: your MCP setup might be different from mine, since I run my Hermes Agent on WSL2, I created a custom host windows.local to target my Window host IP address and reach my Payload through localhost:3000, if you run the Payload in another server or alongside where Hermes Agent is running, you might be able to just use localhost or target the Payload host directly.

Now run your Payload app and call /reload-mcp on your Hermes Agent. If it works, you should see a success message informing PayloadHermesEcommerce MCP has been added to the agent. I used PayloadHermesEcommerce for a more descriptive name. To test out that the MCP works, try asking your Hermes about what products your e-commerce have:

What products does my e-commerce have?

Hermes will use the tools provided in the MCP and return products from your platform.

Things you can do with the integration

Now it's the fun part! With the MCP running, you are able to manage your Payload e-commerce platform in multiple ways. Let's try researching new products and adding it to the listing by sending this message to the agent through Telegram.

Research 3 Y2K styled clothing items and add them to our platform. Make sure each item has at least 1 image you download from the internet to the gallery and descriptive details. Make sure you fill out the SEO details completely.

Next, let's make a few fake users and transactions, then create a PDF report about our store's performance:

Please make 3 fake customers and 20 fake transactions with variative orders, status, and total. Then, create a PDF report about how our platform is performing and recommendations to improve our sales.

There are multitude of ways you can utilize this integration:

Setup cron job to research the market and update the product listing daily
Research and write blog posts or promotion pages with good SEO for your products
Analyze stale carts and automatically send personalized emails to remind the user
Ask about transaction and orders data to create PDF/Excel reports
Feed Hermes with your business information to build a FAQ database
Integrate chatbot feature on the e-commerce client app with distinct personality
Many more! You can ask Hermes to do all of that just through your Telegram, WhatsApp, and any other messaging gateway you setup. This gives admins an easy way to operate your e-commerce platform.

Deployment

I won't go into details on how to deploy this but since Payload CMS is a Next.js app, you can deploy it in Vercel and any other methods such as a VPS. For Hermes Agent, you can deploy it to a VPS and set up the Payload MCP to direct to your deployed Payload app. If you use another database such as Postgres, you need to also deploy and manage that. Since you own the source code and agent setup, you are able to optimize your infrastructure cost based on your needs.

Conclusion

AI agents are developing super quickly and its making building products and automating tasks accessible to a wider range of audience. By using Payload CMS e-commerce template with its MCP plugin capabilities, we can create an AI assistant with Hermes Agent that helps automate your e-commerce operations. Since you now own the e-commerce platform and AI agent, you can optimize your expenses.

Reactively logout users on token refresh failure from Dio interceptors using RxDart in Flutter

Elys Maldov — Sat, 31 Jan 2026 15:33:24 +0000

Firebase auth should cover about 90% of a Flutter app's authentication needs, but what if you need to roll your own auth? Then, you'd need to manually handle trading and saving your JWT tokens from the backend to your app's secure storage.

Now, your JWT should have an expiration date, that means you need to refresh your tokens periodically using the refresh token sent by your backend. All seems good until your user logs in to your app after 60 days, by then your access and refresh tokens should expire, and now you are getting 401 errors in your app.

Your Dio refresh token interceptor should try to get new tokens using the saved refresh token, but if your refresh token is expired, that won't work. If the user is conscious enough, they would try to logout and login again to get new tokens, but wouldn't it be nicer if in cases of refreshing token failures, our app automatically logs the user out?

This might be a rare occurrence, but it was a requirement I had to deal with for a recent project I was working on, Kawal. In this article, I'll explain how I handled refreshing JWT token failures by reactively logging out the user using RxDart. I'll also provide a Flutter app project to explain how the core system works.

Kawal Case Study

The app handles custom JWT authentication using a straightforward flow:

User logs in
Backend responds with an access and refresh token
Store both of these using flutter secure storage
On app startup, read from the secure storage
If both tokens exist, then the user is authenticated

Since I’m binding the existence of those tokens to the users authenticated status, logging out could simply be clearing that token and redirecting the user to the login page. Before we move on, this is how the app's auth system is architected:

The RefreshTokenInterceptor handles refreshing access token by checking if any request responds with a 401 status from the backend. If it does, the interceptor will hit a refresh token endpoint to get and store the new tokens. But, there are situations where refreshing token could fail, for example when the server is down or the refresh token expires. My team agreed that if this happens, we would log the user out.

Now I could have this setup to handle that logout:

Since the existence of auth token is what sets the authentication status, clearing it should suffice. But, our app also have other logic to do during logout:

Clearing shared preferences
Calling Google Analytics These methods are handled by the AuthRepository.logout method, so the architecture really looks like this:

Since the AuthRepository.logout method is the source-of-truth for logging out, now logging out just by clearing the secure storage in the refresh token interceptor is not sufficient. So why not just use AuthRepository inside of the RefreshTokenInterceptor? Well…

Now there’s a circular dependency: Dio is used by AuthService, which is used by AuthRepository, which is used by RefreshTokenInterceptor, which is used by Dio, which is used by AuthService… not good.

One option is to just copy-paste the logout method in AuthRepository to RefreshTokenInterceptor, but I prefer to keep things DRY. So in this article, I’ll show you how you can handle this problem by making use of good ol’ RxDart as a signal for app to logout at any point we want.

Tutorial: Getting user’s profile data using JWT

I've built an example project using Platzi Fake Store API | Platzi Fake Store API since it supports JWT auth. You can clone the repository here to read along the code and I'll explain the core mechanics for the rest of this article.

The app has simple features:

Unauthenticated users must login/register
Authenticated users are redirected to the home screen where they can see their auth-protected user profile

The Platzi API requires us to provide the JWT to get the user’s profile, so this part will be a good example of how we can handle reactive authentication.

RxDart Basic Concepts

Before we dive in to the tutorial, we need to know a few basic concept of RxDart, mainly BehaviorSubject and PublishSubject. These classes are what we call Observables in reactive programming, basically they are “things” our app can “listen” to and based on what “thing” that happened, our app can run certain logic (listeners).

These “things” we listen to are Streams. If you have ever used something like Kafka or Pub/Sub, its basically like how you can publish topics and your subscribers/consumers can react to it by triggering certain callbacks, for example calling a function, API endpoint, etc. With reactive programming, we can send (emit) values over time to the stream and our listeners can receive those values to do whatever they want.

The main difference between BehaviorSubject and PublishSubject is BehaviorSubjects stores the last emitted value to the stream (stateful) while PublishSubjects don’t (ephemeral). So if a new listener comes in, they will instantly receive the last value; unlike PublishSubject that doesn’t store the last emitted value, so new listeners won’t know what happened last time.

We can use these concepts to solve our reactive logout problem. Imagine if we only cleared the auth token from secure storage, then what? Flutter doesn’t know the user should be redirected to the login screen, we have to do it ourselves. But, redirection is a view layer concern, while our AuthRepository.logout method lives in the AuthRepository which should only concern business logic problems. That means, signaling our app to logout consists of 2 steps:

Clearing the auth token from secure storage (data layer)
Redirecting the user to login screen (view layer)

We’ll handle these steps by leveraging reactive programming, we’ll need to setup 2 streams: a stream built with BehaviorSubject to store the user's authentication status and a stream built with PublishSubject to signal our app to logout.

Architecture

This tutorial uses MVVM:

Each layer handles different concerns:

Services: directly calls the Platzi API and returns DTOs (Data Transfer Objects)
Repositories: utilizes multiple services and streams to build the business logic
Cubits: our ViewModel to abstract away our views’ logic by orchestrating multiple repositories and store state
Views: screens that will simply present the data from our cubits states

We’ll also spice things up by introducing dependency injection using get_it. This might seem overkill for this simple app, but I find this setup as a good basis when managing my app that has a lot of business logic and screens going around.

Create AppSignal to emit logout signal

We need a signal that is accessible to any layer of our app without causing a circular dependency. We can fix this easily by creating a dependency called AppSignal that stores any global signals our app can emit/listen to.

// lib/data/core/app_signals.dart
import 'package:logging/logging.dart';
import 'package:rxdart/rxdart.dart';

class AppSignals {
  final _log = Logger('AppSignals');

  final _logoutSignalSubject = PublishSubject<Null>();
  Stream<Null> get logoutSignalStream => _logoutSignalSubject.stream;

  Future<void> emitLogoutSignal() async {
    _log.info('Emitting logout signal');
    _logoutSignalSubject.add(null);
    _log.info('Logout signal emitted');
  }
}

We expose a logoutSignalStream that will be listened to by our app to trigger AuthRepository.logout method. With the emitLogoutSignal, we can signal our app to logout anytime and anywhere, since this dependency is a core dependency that can be used on any layer of our app that has access to get_it/any other DI framework you implement.

Listen to logoutSignalStream in AuthRepository

I placed my logout method in AuthRepository, alongside a BehaviorSubject to store the user's current auth status. The logout method will be responsible to clear the auth token, update the user's auth status stream, and do other things such as sending analytics.

// lib/data/repositories\auth_repository.dart
import 'package:flutter_reactive_logout_example/data/core/app_error.dart';
import 'package:flutter_reactive_logout_example/data/core/app_signals.dart';
import 'package:flutter_reactive_logout_example/data/services/auth_service.dart';
import 'package:flutter_reactive_logout_example/data/storage/secure_storage.dart';
import 'package:flutter_reactive_logout_example/domain/enums/auth_status.dart';
import 'package:flutter_reactive_logout_example/domain/models/auth_token.dart';
import 'package:flutter_reactive_logout_example/domain/models/login_request.dart';
import 'package:flutter_reactive_logout_example/domain/models/register_request.dart';
import 'package:flutter_reactive_logout_example/domain/models/user.dart';
import 'package:logging/logging.dart';
import 'package:rxdart/rxdart.dart';

abstract class AuthRepository {
  Stream<AuthStatus> get authStatusStream;
  AuthStatus get currentAuthStatus;

  Future<void> register(RegisterRequest registerRequest);
  Future<void> login(LoginRequest loginRequest);
  Future<User> getUserProfile();

  Future<void> logout();
  void dispose();
}

class AuthRepositoryRemote extends AuthRepository {
  final Logger _log = Logger('AuthRepositoryRemote');
  final AuthService _authService;
  final SecureStorage _secureStorage;
  final AppSignals _appSignals;

  final BehaviorSubject<AuthStatus> _authStatusSubject =
      BehaviorSubject<AuthStatus>.seeded(AuthStatus.unknown);
  @override
  Stream<AuthStatus> get authStatusStream => _authStatusSubject.stream;
  @override
  AuthStatus get currentAuthStatus => _authStatusSubject.value;

  AuthRepositoryRemote({
    required AuthService authService,
    required SecureStorage secureStorage,
    required AppSignals appSignals,
  }) : _authService = authService,
       _secureStorage = secureStorage,
       _appSignals = appSignals {
    // ...
    _listenToLogoutSignal();
  }

  void _listenToLogoutSignal() {
    _appSignals.logoutSignalStream.listen((_) async {
      _log.info('Logout signal received, performing logout');
      await logout();
    });
  }

  // ...

  @override
  Future<void> logout() async {
    try {
      _log.info('Logging out user');
      await _secureStorage.clearAuthToken();
      // TODO do other things (send analytics, clear shared preferences, etc.)
      _authStatusSubject.add(AuthStatus.unauthenticated);
      _log.info('Logout successful');
    } catch (e, stack) {
      final appError = _mapToAppError(e);
      _log.severe('Logout failed', appError, stack);
      _authStatusSubject.add(AuthStatus.unauthenticated);
      throw appError;
    }
  }

  // ...
}

During the construction of the class, we depend on the AppSignals and listen to its logoutSignalStream to trigger the logout method. Later, the rest of our app can emit a logout signal and our AuthRepository will handle logging out. This is much cleaner, since if we ever need to modify the logout method, we just have to modify it in this one repository.

Emit logout signal in refresh token interceptor

We'll handle refreshing the user's token using a Dio interceptor.

// lib/config/dio/interceptors/refresh_token_interceptor.dart
import 'package:dio/dio.dart';
import 'package:flutter_reactive_logout_example/config/api_routes.dart';
import 'package:flutter_reactive_logout_example/data/core/app_error.dart';
import 'package:flutter_reactive_logout_example/data/core/app_signals.dart';
import 'package:flutter_reactive_logout_example/data/storage/secure_storage.dart';
import 'package:flutter_reactive_logout_example/domain/models/auth_token.dart';
import 'package:logging/logging.dart';

/// Uses [QueuedInterceptorsWrapper] so if multiple request fails at once, we refresh
/// the first one before retrying the rest using the new token
class RefreshTokenInterceptor extends QueuedInterceptorsWrapper {
  final Dio _dio;
  final SecureStorage _storage;
  final AppSignals _appSignals;
  final _log = Logger('RefreshTokenInterceptor');

  RefreshTokenInterceptor({
    required Dio dio,
    required SecureStorage storage,
    required AppSignals appSignals,
  }) : _dio = dio,
       _storage = storage,
       _appSignals = appSignals;

  // ...

  @override
  Future<void> onError(
    DioException err,
    ErrorInterceptorHandler handler,
  ) async {
    final isUnauthorized = err.response?.statusCode == 401;
    // Avoid infinite loop if the refresh-token endpoint itself fails
    final isRefreshRequest = err.requestOptions.path.contains(
      ApiRoutes.refreshToken,
    );

    if (isUnauthorized && !isRefreshRequest) {
      _log.warning('Token expired! Refreshing token...');

      // ... handle refreshing logic

      } catch (e) {
        _log.severe('Refresh token failed. Logging user out', e);
        final appError = AppError.from(e);

        // Important piece to signal logout for our app
        _appSignals.emitLogoutSignal();

        return handler.next(
          DioException(requestOptions: err.requestOptions, error: appError),
        );
      }
    }

    return handler.next(err);
  }
}

Notice how it wraps the refreshing logic in a try/catch, and the catch block calls _appSignals.emitLogoutSignal(). Whenever the refresh token logic fails, we can assume the user should logout to get new tokens. By calling that method, we'll trigger the listener in AppRepository earlier that calls the logout method. Side note, this interceptor only runs if your request encounters an error, specifically a 401 error. My team agreed that encountering a 401 status means the user should try to refresh their tokens, but your requirement may vary.

Reactively navigate using GoRouter's refreshListenable

So far we've only managed the auth status in the data layer, but haven't really tied it with the app's actual navigation to the login screen. We can use GoRouter's refreshListenable to listen to a Listenable and trigger navigation whenever that Listenable changes.

// lib/routing/router.dart
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_reactive_logout_example/domain/enums/auth_status.dart';
import 'package:go_router/go_router.dart';
import 'package:flutter_reactive_logout_example/config/dependencies.dart';
import 'package:flutter_reactive_logout_example/data/repositories/auth_repository.dart';
import 'package:flutter_reactive_logout_example/ui/home/cubit/home_cubit.dart';
import 'package:flutter_reactive_logout_example/ui/home/widgets/home_screen.dart';
import 'package:flutter_reactive_logout_example/ui/login/cubit/login_cubit.dart';
import 'package:flutter_reactive_logout_example/ui/login/widgets/login_screen.dart';
import 'package:flutter_reactive_logout_example/ui/register/cubit/register_cubit.dart';
import 'package:flutter_reactive_logout_example/ui/register/widgets/register_screen.dart';
import 'package:flutter_reactive_logout_example/ui/splash/splash_screen.dart';
import 'routes.dart';

/// AppRouter class that configures go_router with authentication guard and reactive navigation
class AppRouter extends ChangeNotifier {
  AppRouter() {
    _setupAuthListener();
  }

  final AuthRepository _authRepository =
      DependencyManager.get<AuthRepository>();

  /// Listen to any stream from any repositories to reactively update the user's navigation
  void _setupAuthListener() {
    _authRepository.authStatusStream.listen((_) {
      notifyListeners();
    });
  }

  /// Creates the GoRouter instance with auth guard and route configuration
  GoRouter get router {
    return GoRouter(
      initialLocation: Routes.splashScreen,
      redirect: _handleRedirect,
      routes: _routes,
      refreshListenable: this,
    );
  }

  /// Auth guard redirect logic
  /// Listens to authStatusStream and redirects based on authentication state
  Future<String?> _handleRedirect(
    BuildContext context,
    GoRouterState state,
  ) async {
    final authRepository = DependencyManager.get<AuthRepository>();
    final authStatus = authRepository.currentAuthStatus;

    final location = state.uri.toString();

    // Define public routes that don't require authentication
    final isPublicRoute =
        location == Routes.login || location == Routes.register;

    // Handle redirect based on auth status
    switch (authStatus) {
      case AuthStatus.authenticated:
        if (location == Routes.splashScreen || isPublicRoute) {
          return Routes.home;
        }
        break;

      case AuthStatus.unauthenticated:
        if (!isPublicRoute) {
          return Routes.login;
        }
        break;

      case AuthStatus.unknown:
        break;
    }

    return null;
  }

  /// Route definitions
  List<GoRoute> get _routes => [
    GoRoute(
      path: Routes.splashScreen,
      name: 'splash',
      builder: (context, state) => const SplashScreen(),
    ),
    GoRoute(
      path: Routes.login,
      name: 'login',
      builder: (context, state) => BlocProvider(
        create: (context) =>
            LoginCubit(authRepository: DependencyManager.get<AuthRepository>()),
        child: const LoginScreen(),
      ),
    ),
    GoRoute(
      path: Routes.register,
      name: 'register',
      builder: (context, state) => BlocProvider(
        create: (context) => RegisterCubit(
          authRepository: DependencyManager.get<AuthRepository>(),
        ),
        child: const RegisterScreen(),
      ),
    ),
    GoRoute(
      path: Routes.home,
      name: 'home',
      builder: (context, state) => BlocProvider(
        create: (context) =>
            HomeCubit(authRepository: DependencyManager.get<AuthRepository>()),
        child: const HomeScreen(),
      ),
    ),
  ];
}

The way I did it is by wrapping the router in a class that extends ChangeNotifier. This effectively turns this into a Listenable that the router listens to. This allows us to listen to multiple streams and notify the Listenable (such as the _setupAuthListener method), that will then, trigger the redirect method of the router. The _handleRedirect method will be triggered whenever we notify something through a stream listener or any other method inside of the class.
We can then wrap the router around the main app:

// lib/main.dart
import 'package:flutter/material.dart';
import 'package:flutter_reactive_logout_example/config/dependencies.dart';
import 'package:flutter_reactive_logout_example/routing/router.dart';
import 'package:logging/logging.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  Logger.root.level = Level.ALL;
  Logger.root.onRecord.listen((record) {
    debugPrint('${record.level.name}: ${record.time}: ${record.message}');
  });
  await DependencyManager.setup();
  runApp(const MainApp());
}

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

  @override
  Widget build(BuildContext context) {
    final appRouter = AppRouter();

    return MaterialApp.router(
      routerConfig: appRouter.router,
      title: 'Flutter Reactive Logout Example',
      debugShowCheckedModeBanner: false,
    );
  }
}

Now, we have finished tying together our logout signal to our app's navigation:

Refresh token fails, emit logout signal in RefreshTokenInterceptor
AuthRepository listen to logout signal to call logout, which will update our authStatusStream into unauthenticated
AppRouter.router listens to the auth status change, and redirect user to the login page since they are now unauthenticated

That's it!

By leveraging RxDart, we can store the user's auth status and signal our app to logout by exposing streams. Our app signals can be listened to by any layer of our app since its a core dependency. We utilize this by emitting logout signal when token refresh fails, which will reactively update our auth status and redirec the user to the login screen.
You should run the demo app to see how the interceptor and stream works. There is a demo logout button in home_screen.dart that will always trigger the RefreshTokenInterceptor catch block.

Have you ever encountered a similar situation where you need to logout the user when the token refresh fails? I'd love to hear your experiences in the comments!

[DEVLOG] Payload CMS Booster: Day 1 - 2

Elys Maldov — Tue, 13 Jan 2026 16:19:45 +0000

I've been using Payload CMS a lot, and I believe it's becoming a pretty hot emerging tech in the Next.js space. As someone who's used to building APIs in Express and developing admin dashboards in React from scratch, it gets pretty tedious when basic APIs and logic (like CRUD-ing a table or handling login screens) get repeated over and over.

Sure, I've used Prisma, Drizzle, tRPC, admin dashboard templates, and the good ol' CTRL+C CTRL+V, but still having to separately handle the backend and frontend for a feature felt like it could be easier. So you should see my face when I first tried out Payload CMS with its config-based approach of building the frontend, backend, and even the data layer of an app. It's so much quicker to declare a Payload collection, which is then generated as a frontend in the admin dashboard, backend APIs, and Drizzle schemas with TypeScript interfaces for me to use instantly. This process would've taken me hours or even days if I were to use my good ol' MERN stack, but with Payload its just instant!

I have no qualms with Payload's DX (though the documentation for advanced use-cases does leave much to be desired), but I'm starting to feel friction when working on a large Payload project with about 20+ collections. My biggest Payload project, Akasia Education, has about 30+ collections with some of them having complex relationships/join fields to multiple other collections. Having an ERD does help, but it's hard for me to actually visualize how it's implemented in Payload CMS. I would have to read each payload collection individually, see their relationship/join field, and imagine it in my head if it fits with my ERD or not. I even encountered errors that were hard to debug due to my collections having multiple relationships with other collections, where those collections have relationships with other collections, and so forth.

Usually, finding where a piece of variable/function/class is used on a project is easy in an IDE with features like go-to definitions or find all references. But finding where a Payload collection is referenced by other collections is more difficult since relationship/join fields use another collection's slug, which are just strings that cannot be used for go-to definitions/find all references in IDEs. So, being inspired by Code Canvas extension and always wanting to make a VSCode extension on my own, is it possible to build a Payload CMS collection visualizer where I can simply see how each collection relates to one another?

The idea

It's super simple: get all Payload collection in a project, analyze their relationship, and visualize them in a canvas like above. Having something like this would really help me visualize my big Payload project without having to take out a pen-and-pencil or always compare it againts my ERD.

Making sure it's possible

With nothing else to do in my free time, I just started building this extension idea. The main idea is that my extension can be activated on a Payload CMS project, and it will traverse the collections to build a visualizer to show how each collection relates to the others. Basically, I want to make something like Code Canvas, but for Payload collections.

Obivously the first thing I need to ensure is if it's even possible. Well, if Code Canvas is possible, then of course this idea should also be. Specifically, I need to make sure how I would implement this and what stack I need.

Reading VSCode extension development docs, it is possible by making a webview-based extension. Frankly, there's not much structured resource on how to build a webview VSCode extension, but after some digging, I found 2 good repositories to serve as a boilerplate: Microsoft's official example and QiyuanChen02 repo.

Ultimately, I chose QiyuanChen02's repo since its newer, but these 2 repo provides a boilerplate for VSCode webview extension using React + Vite and hot-reload. The gist of the development flow is I just build a normal React app whose built code will be rendered as a webview in VSCode, and I can pass messages between VSCode and my webview using message passing. Next is how to render the visualizer. I chose React Flow since it's super popular for this.

Now that the basic prerequisite is possible for me to build the extension, it's time to actually build the extension and not abandon it as another side project.

Actually building the extension

I forked QiyuanChen02's repo to quickly bootstrap my extension project here: https://github.com/ElysMaldov/payload-cms-booster. I called it Payload CMS Booster because I have a few other ideas for this extension to boost working with Payload in VSCode. It just works by running the debug mode (F5), it will open up another VSCode window with my custom command to show the React app in a webview. I added a new launch JSON that starts the debug VSCode window in a clean slate by disabling all other extensions except the one I'm developing and also opening an existing Payload project to test it later; I placed this new debug config in the launch.json.

For the folder structure, it's quite straightforward. I have a "root" project with the main entrypoint being the src/extension.ts. This is where I register my webview to the extension. The webview takes in the dist folder of the React webview subproject in the webview folder. I have 2 projects, each having its own dependencies. For now, this works, but I could potentially turn it into a monorepo like how Kilo Code does it.

To run the project, I need to run the dev server in the webview project and start a debugger to open up another VSCode window. In that new window, I can access the command to bring up the webview (currently the command is "Payload CMS Booster: Visualize" specified in the root package.json or VSCode calls it extension manifest). Then I can just work on the webview project like a regular React + Vite project with HMR working.

The latest progress I made with this repo is setting up an example React Flow component. I haven't really thought much about how to architect this project but I'll try applying parts of MVVM since I've been working on a lot of Flutter these days; mainly I need to separate between the data and UI layer, and use domain models a lot so I don't have to worry much about how to pass my actual payload collection data from VSCode since I can just assume that's a DTO I need to map to my domain model.

So my next step is how can I traverse all of the Payload collection in a project, analyze their relationships with each other, and structure it for my webview and finally render it in React Flow? The idea I have so far is to read the payload.config.ts, iterate through each collection to collect their slug, and build their relationship based on the existence of either a relationship/join field in that collection. This seems okay so far since a relationship/join field refers to another collection using their unique slug, so I could use this as an id for each collection. I thought about using the generated payload-types.ts file, but it seems wayyyy more complicated than a regular Payload collection file.

I'll update again soon 😸.