From 0783d830a1a56c2d6a2e1769d67e7b2c3aae2432 Mon Sep 17 00:00:00 2001 From: Stefanos Anagnostou Date: Fri, 6 Dec 2024 18:20:03 +0200 Subject: [PATCH 01/12] Add the Expo Offline support page --- docs/manifest.json | 4 ++ docs/references/expo/offline-support.mdx | 73 ++++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 docs/references/expo/offline-support.mdx diff --git a/docs/manifest.json b/docs/manifest.json index 7f84702730..5f5454e090 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2301,6 +2301,10 @@ ] ] }, + { + "title": "Offline support", + "href": "/docs/references/expo/offline-support" + }, { "title": "Guides", "items": [ diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx new file mode 100644 index 0000000000..e55515f322 --- /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 about updates in the package. + +## Overview + +The `@clerk/clerk-expo` package 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: + +- Faster resolution of the `isLoaded` property and the `ClerkLoaded` control component with only a single network fetch attempt. If the fetch fails, it gracefully falls back to cached resources. +- The `getToken` function in the `useAuth` hook now supports returning cached tokens, minimizing disruptions caused by network failures. +- Network errors are no longer muted, allowing developers to catch and handle them effectively in their custom flows. + +## How to enable offline support + +To enable offline support in your Expo app, follow these steps: + + + ### Install the necessary peer dependencies + + The `expo-secure-store` package is required to be installed in order to use the offline support feature. + + + ```bash {{ filename: 'terminal' }} + npm install expo-secure-store + ``` + + ```bash {{ filename: 'terminal' }} + yarn add expo-secure-store + ``` + + ```bash {{ filename: 'terminal' }} + pnpm add expo-secure-store + ``` + + + ### Use the `__experimental_resourceCache` property + + On `ClerkProvider`, use the `__experimental_resourceCache` property and pass the `secureStore` object from `@clerk/clerk-expo/secure-store`. + + ```tsx {{ filename: 'app/_layout.tsx' }} + 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 ( + + + + + + ) + } + ``` + From c164e82e9400ae428a08a69bb910a8acaeea20a6 Mon Sep 17 00:00:00 2001 From: Stefanos Anagnostou Date: Fri, 6 Dec 2024 18:25:04 +0200 Subject: [PATCH 02/12] fix warning --- docs/references/expo/offline-support.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx index e55515f322..0e503bea99 100644 --- a/docs/references/expo/offline-support.mdx +++ b/docs/references/expo/offline-support.mdx @@ -4,7 +4,8 @@ description: Learn how to enable offline support in your Expo app with Clerk. --- > [!WARNING] -> This is an experimental API. +> **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 about updates in the package. ## Overview From 299115a25346d4823a6aa45a42adc6bb96617f84 Mon Sep 17 00:00:00 2001 From: Stefanos Anagnostou Date: Fri, 6 Dec 2024 18:26:41 +0200 Subject: [PATCH 03/12] fix title --- docs/references/expo/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx index 0e503bea99..28e3aa27d3 100644 --- a/docs/references/expo/offline-support.mdx +++ b/docs/references/expo/offline-support.mdx @@ -41,7 +41,7 @@ To enable offline support in your Expo app, follow these steps: ``` - ### Use the `__experimental_resourceCache` property + ### Use the `__experimental_resourceCache` property on `ClerkProvider` On `ClerkProvider`, use the `__experimental_resourceCache` property and pass the `secureStore` object from `@clerk/clerk-expo/secure-store`. From 9df78c1f23392ebf895f6a4eb201bbb9f43f4b20 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Fri, 6 Dec 2024 18:02:32 -0500 Subject: [PATCH 04/12] code review --- docs/references/expo/offline-support.mdx | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx index 28e3aa27d3..2ef7a40749 100644 --- a/docs/references/expo/offline-support.mdx +++ b/docs/references/expo/offline-support.mdx @@ -8,14 +8,12 @@ description: Learn how to enable offline support in your Expo app with Clerk. > > 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 about updates in the package. -## Overview - -The `@clerk/clerk-expo` package 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. +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: -- Faster resolution of the `isLoaded` property and the `ClerkLoaded` control component with only a single network fetch attempt. If the fetch fails, it gracefully falls back to cached resources. -- The `getToken` function in the `useAuth` hook now supports returning cached tokens, minimizing disruptions caused by network failures. +- Faster resolution of the `isLoaded` property and the [``](/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. +- The [`getToken()`](/docs/references/javascript/session#get-token) function in the `useAuth()` hook now supports returning cached tokens, minimizing disruptions caused by network failures. - Network errors are no longer muted, allowing developers to catch and handle them effectively in their custom flows. ## How to enable offline support @@ -25,7 +23,7 @@ To enable offline support in your Expo app, follow these steps: ### Install the necessary peer dependencies - The `expo-secure-store` package is required to be installed in order to use the offline support feature. + The `expo-secure-store` package is required to use the offline support feature. ```bash {{ filename: 'terminal' }} @@ -43,9 +41,9 @@ To enable offline support in your Expo app, follow these steps: ### Use the `__experimental_resourceCache` property on `ClerkProvider` - On `ClerkProvider`, use the `__experimental_resourceCache` property and pass the `secureStore` object from `@clerk/clerk-expo/secure-store`. + On [``](/docs/components/clerk-provider), pass the `secureStore` object to the `__experimental_resourceCache` property, as shown in the following example: - ```tsx {{ filename: 'app/_layout.tsx' }} + ```tsx {{ filename: 'app/_layout.tsx', mark: [[14, 18]] }} import { ClerkProvider, ClerkLoaded } from '@clerk/clerk-expo' import { Slot } from 'expo-router' import { tokenCache } from '../token-cache' From c4fc4e6f92f08f917b6e49d1eace74e2d77a811a Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 10 Dec 2024 11:07:29 -0500 Subject: [PATCH 05/12] highlight line 4 --- docs/references/expo/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx index 2ef7a40749..d5d7ef2479 100644 --- a/docs/references/expo/offline-support.mdx +++ b/docs/references/expo/offline-support.mdx @@ -43,7 +43,7 @@ To enable offline support in your Expo app, follow these steps: On [``](/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: [[14, 18]] }} + ```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' From d48ba698f87e2ac73d39e0d33e6584aa04470060 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 10 Dec 2024 12:38:07 -0500 Subject: [PATCH 06/12] fix hooks section in sidenav --- docs/manifest.json | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 5f5454e090..a0cc48f281 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2282,8 +2282,15 @@ "href": "/docs/references/expo/overview" }, { - "title": "useLocalCredentials()", - "href": "/docs/references/expo/use-local-credentials" + "title": "Hooks", + "items": [ + [ + { + "title": "useLocalCredentials()", + "href": "/docs/references/expo/use-local-credentials" + } + ] + ] }, { "title": "Web support", From 218d023d8ef225fa7addfb316228da0156c06c24 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 10 Dec 2024 12:39:38 -0500 Subject: [PATCH 07/12] add use-oauth to hooks in sidenav --- docs/manifest.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/manifest.json b/docs/manifest.json index a0cc48f281..d367191da1 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2288,6 +2288,10 @@ { "title": "useLocalCredentials()", "href": "/docs/references/expo/use-local-credentials" + }, + { + "title": "useOAuth()", + "href": "/docs/references/expo/use-oauth" } ] ] From bbf5545b42c2c3548fa6af030a3f5c9dbf74b194 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 10 Dec 2024 12:55:25 -0500 Subject: [PATCH 08/12] update sidenav (manifest.json) --- docs/manifest.json | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index d367191da1..990485ebb9 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2297,36 +2297,36 @@ ] }, { - "title": "Web support", - "collapse": true, + "title": "Guides", "items": [ [ { - "title": "Overview", - "href": "/docs/references/expo/web-support/overview" + "title": "Read session and user data", + "href": "/docs/references/expo/read-session-user-data" }, { - "title": "Add custom sign-up and sign-in pages", - "href": "/docs/references/expo/web-support/custom-signup-signin-pages" + "title": "Use biometrics with local credentials", + "href": "/docs/references/expo/local-credentials" + }, + { + "title": "Offline support", + "href": "/docs/references/expo/offline-support" } ] ] }, { - "title": "Offline support", - "href": "/docs/references/expo/offline-support" - }, - { - "title": "Guides", + "title": "Web support", + "collapse": true, "items": [ [ { - "title": "Read session and user data", - "href": "/docs/references/expo/read-session-user-data" + "title": "Overview", + "href": "/docs/references/expo/web-support/overview" }, { - "title": "Use biometrics with local credentials", - "href": "/docs/references/expo/local-credentials" + "title": "Add custom sign-up and sign-in pages", + "href": "/docs/references/expo/web-support/custom-signup-signin-pages" } ] ] From 00704035581fb392be5bf43266ec053a266ef9c2 Mon Sep 17 00:00:00 2001 From: Stefanos Anagnostou Date: Wed, 11 Dec 2024 11:44:06 +0200 Subject: [PATCH 09/12] Add changelog link --- docs/references/expo/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx index d5d7ef2479..b47f09d71e 100644 --- a/docs/references/expo/offline-support.mdx +++ b/docs/references/expo/offline-support.mdx @@ -6,7 +6,7 @@ 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 about updates in the package. +> 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 thorough [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. From 3f732b2959fb0a048d3d7567e4e384f7cc2645d4 Mon Sep 17 00:00:00 2001 From: Stefanos Anagnostou Date: Wed, 11 Dec 2024 18:20:13 +0200 Subject: [PATCH 10/12] add one more benefit --- docs/references/expo/offline-support.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx index b47f09d71e..baf83da4bd 100644 --- a/docs/references/expo/offline-support.mdx +++ b/docs/references/expo/offline-support.mdx @@ -12,9 +12,10 @@ The Clerk Expo SDK provides enhanced offline support to improve reliability and 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 [``](/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. -- The [`getToken()`](/docs/references/javascript/session#get-token) function in the `useAuth()` hook now supports returning cached tokens, minimizing disruptions caused by network failures. - 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 From 49b091fd6c444df775a3630c43d3405f85e4fc30 Mon Sep 17 00:00:00 2001 From: Stefanos Anagnostou Date: Wed, 11 Dec 2024 20:16:52 +0200 Subject: [PATCH 11/12] fix manifest --- docs/manifest.json | 31 ++++++++++--------------------- docs/manifest.schema.json | 3 ++- 2 files changed, 12 insertions(+), 22 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index e744fe2a81..5e376f709a 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2293,16 +2293,21 @@ "href": "/docs/references/expo/overview" }, { - "title": "Hooks", + "title": "useLocalCredentials()", + "href": "/docs/references/expo/use-local-credentials" + }, + { + "title": "Web support", + "collapse": true, "items": [ [ { - "title": "useLocalCredentials()", - "href": "/docs/references/expo/use-local-credentials" + "title": "Overview", + "href": "/docs/references/expo/web-support/overview" }, { - "title": "useOAuth()", - "href": "/docs/references/expo/use-oauth" + "title": "Add custom sign-up and sign-in pages", + "href": "/docs/references/expo/web-support/custom-signup-signin-pages" } ] ] @@ -2325,22 +2330,6 @@ } ] ] - }, - { - "title": "Web support", - "collapse": true, - "items": [ - [ - { - "title": "Overview", - "href": "/docs/references/expo/web-support/overview" - }, - { - "title": "Add custom sign-up and sign-in pages", - "href": "/docs/references/expo/web-support/custom-signup-signin-pages" - } - ] - ] } ] ] diff --git a/docs/manifest.schema.json b/docs/manifest.schema.json index dce30cb164..fe5a0a7c7b 100644 --- a/docs/manifest.schema.json +++ b/docs/manifest.schema.json @@ -137,7 +137,8 @@ "user-circle", "user-dotted-circle", "vue", - "x" + "x", + "expo" ] } } From d3194cb4c5f2aa22464b8d9bd95557fa33307ff8 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 11 Dec 2024 13:20:29 -0500 Subject: [PATCH 12/12] Update docs/references/expo/offline-support.mdx --- docs/references/expo/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/expo/offline-support.mdx b/docs/references/expo/offline-support.mdx index baf83da4bd..a281071efa 100644 --- a/docs/references/expo/offline-support.mdx +++ b/docs/references/expo/offline-support.mdx @@ -6,7 +6,7 @@ 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 thorough [the package's changelog](https://github.com/clerk/javascript/blob/main/packages/expo/CHANGELOG.md). +> 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.