Offline First

Hyper-fetch is designed with offline-first and data persistence in mind. This means our request queueing system is fully equipped to help you build robust offline-first applications. When your application goes offline, Hyper-fetch automatically pauses outgoing requests and seamlessly resumes them once the connection is restored.

This entire process is managed by the AppManager, which monitors the application's state, such as online/offline status and whether the app window is focused or blurred.

---

What you'll learn

1. How Hyper-fetch automates offline request handling.
2. The role of the AppManager in detecting network status.
3. How to provide custom logic for online/offline detection for environments like React Native.
4. How to integrate with libraries like @react-native-community/netinfo.

Default Behavior

By default, Hyper-fetch listens to the browser's online and offline events to manage the request queue. No extra configuration is needed for this to work in a standard web environment. When the browser detects a lost connection, the AppManager puts all active and queued requests on hold. Once the connection returns, it automatically resumes them.

Marking Requests for Offline Support

For a request to be queued when offline (instead of failing immediately), you must mark it with offline: true:

const createPost = client.createRequest()({
  endpoint: "/posts",
  method: "POST",
  offline: true,
});

// If the user is offline when this is called, the request will be queued
// and automatically sent when the connection is restored
createPost.send({ payload: { title: "My Post", content: "Written offline" } });

Without offline: true, requests made while offline will fail immediately with an error.

Combining with Queuing

For the best offline experience, combine offline: true with queued: true. This ensures that multiple offline requests are sent sequentially once the connection is restored, avoiding overwhelming the server:

const syncAction = client.createRequest()({
  endpoint: "/sync",
  method: "POST",
  offline: true,
  queued: true,
});

Customization

The default browser events are not always available in non-browser environments like React Native. For these cases, you can provide your own logic for detecting the connection status.

React Native Example

In React Native, @react-native-community/netinfo is the standard way to get information about the device's network status. You can integrate it with Hyper-fetch's AppManager like this:

import { Client, AppManager } from "@hyper-fetch/core";
// import NetInfo from "@react-native-community/netinfo";

const client = new Client({
  url: "https://api.example.com",
  appManager: () =>
    new AppManager({
      initiallyOnline: () => {
        return new Promise((resolve) => {
          NetInfo.fetch().then((state) => {
            resolve(state.isConnected);
          });
        });
      },
      onlineEvent: (setOnline) => {
        const unsubscribe = NetInfo.addEventListener((state) => {
          setOnline(state.isConnected);
        });

        // Return an unsubscribe function to clean up the listener
        return unsubscribe;
      },
    }),
});

In this example:

1. initiallyOnline: We use NetInfo.fetch() to get the current network state when the app starts. This returns a promise that resolves with the connection status.
2. onlineEvent: We set up an event listener with NetInfo.addEventListener. This listener calls setOnline with the current connection status whenever it changes. The function returns the unsubscribe function from NetInfo, which AppManager will call to clean up the listener when it's no longer needed.

This setup ensures that Hyper-fetch's offline handling works seamlessly in a React Native environment.

---

Congratulations!

You've learned how to handle offline state with Hyper-fetch!

• You know that Hyper-fetch provides automatic offline handling out of the box.
• You can customize the online/offline detection logic using the AppManager.
• You are able to integrate Hyper-fetch with environment-specific network status libraries like @react-native-community/netinfo.
• You can now build powerful offline-first applications.