From 8bf4b2b34637bfcccb018ca8ab82dc0fa9bd9ad9 Mon Sep 17 00:00:00 2001
From: Stefanos Anagnostou <anagstef@users.noreply.github.com>
Date: Thu, 12 Dec 2024 22:01:03 +0200
Subject: [PATCH] Add the Expo Offline support page (#1781)

Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
---
 docs/manifest.json                       |  4 ++
 docs/manifest.schema.json                |  3 +-
 docs/references/expo/offline-support.mdx | 73 ++++++++++++++++++++++++
 3 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 docs/references/expo/offline-support.mdx

diff --git a/docs/manifest.json b/docs/manifest.json
index 4b6bc45721..4973d041a6 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -2313,6 +2313,10 @@
                         {
                           "title": "Use biometrics with local credentials",
                           "href": "/docs/references/expo/local-credentials"
+                        },
+                        {
+                          "title": "Offline support",
+                          "href": "/docs/references/expo/offline-support"
                         }
                       ]
                     ]
diff --git a/docs/manifest.schema.json b/docs/manifest.schema.json
index d2e07cba0d..1909c9e4e3 100644
--- a/docs/manifest.schema.json
+++ b/docs/manifest.schema.json
@@ -138,7 +138,8 @@
         "user-circle",
         "user-dotted-circle",
         "vue",
-        "x"
+        "x",
+        "expo"
       ]
     }
   }
diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx
new file mode 100644
index 0000000000..a281071efa
--- /dev/null
+++ b/docs/references/expo/offline-support.mdx
@@ -0,0 +1,73 @@
+---
+title: Enable offline support in your Expo app
+description: Learn how to enable offline support in your Expo app with Clerk.
+---
+
+> [!WARNING]
+> **This is an experimental API.**
+>
+> The `__experimental_resourceCache` property introduced in this guide is an experimental feature. It is subject to change in future updates, so use it cautiously in production environments. Ensure thorough testing and stay informed through [the package's changelog](https://github.com/clerk/javascript/blob/main/packages/expo/CHANGELOG.md).
+
+The Clerk Expo SDK provides enhanced offline support to improve reliability and user experience. This update enables your app to bootstrap offline using cached Clerk resources, ensuring quick initialization without requiring an internet connection.
+
+It offers the following benefits:
+
+- Initialization of the Clerk SDK is now more resilient to network failures.
+- Faster resolution of the `isLoaded` property and the [`<ClerkLoaded>`](/docs/components/control/clerk-loaded) control component with only a single network fetch attempt. If the fetch fails, it gracefully falls back to cached resources.
+- Network errors are no longer muted, allowing developers to catch and handle them effectively in their custom flows.
+- The [`getToken()`](/docs/references/javascript/session#get-token) function in the `useAuth()` hook now supports returning cached tokens, minimizing disruptions caused by network failures.
+
+## How to enable offline support
+
+To enable offline support in your Expo app, follow these steps:
+
+<Steps>
+  ### Install the necessary peer dependencies
+
+  The `expo-secure-store` package is required to use the offline support feature.
+
+  <CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
+    ```bash {{ filename: 'terminal' }}
+    npm install expo-secure-store
+    ```
+
+    ```bash {{ filename: 'terminal' }}
+    yarn add expo-secure-store
+    ```
+
+    ```bash {{ filename: 'terminal' }}
+    pnpm add expo-secure-store
+    ```
+  </CodeBlockTabs>
+
+  ### Use the `__experimental_resourceCache` property on `ClerkProvider`
+
+  On [`<ClerkProvider>`](/docs/components/clerk-provider), pass the `secureStore` object to the `__experimental_resourceCache` property, as shown in the following example:
+
+  ```tsx {{ filename: 'app/_layout.tsx', mark: [4, [14, 18]] }}
+  import { ClerkProvider, ClerkLoaded } from '@clerk/clerk-expo'
+  import { Slot } from 'expo-router'
+  import { tokenCache } from '../token-cache'
+  import { secureStore } from '@clerk/clerk-expo/secure-store'
+
+  export default function RootLayout() {
+    const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY!
+
+    if (!publishableKey) {
+      throw new Error('Add EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY to your .env file')
+    }
+
+    return (
+      <ClerkProvider
+        publishableKey={publishableKey}
+        tokenCache={tokenCache}
+        __experimental_resourceCache={secureStore}
+      >
+        <ClerkLoaded>
+          <Slot />
+        </ClerkLoaded>
+      </ClerkProvider>
+    )
+  }
+  ```
+</Steps>