Apollo Client Reactive Variables state persistence during page refreshes

Answer to the Core Questions

1. Recommended pattern for persistence: Create the reactive variable so that its initializer reads from localStorage and, whenever the variable changes, write the new value back. The typical implementation is a small helper that encapsulates this read/write logic.

2. Built‑in hydration support: Apollo Client does not ship a built‑in mechanism to hydrate reactive variables from persistent storage. The hydration logic must be written manually, as shown below.

Why This Pattern Works

Reactive variables live only in memory. A page reload discards them, so the only way to survive is to store the value somewhere persistent and restore it on startup. By tying the variable’s initializer to localStorage and synchronizing writes, the variable behaves as if it were always persisted.

Step‑by‑Step Implementation

1. Define a helper that accepts a storage key and an initial value:

   import { makeVar } from '@apollo/client';
   
   function usePersistentVar(key, defaultValue) {
     const stored = localStorage.getItem(key);
     const initial = stored ? JSON.parse(stored) : defaultValue;
     const varRef = makeVar(initial);
   
     // Keep localStorage in sync whenever the var changes
     const set = (newVal) => {
       varRef(newVal);
       localStorage.setItem(key, JSON.stringify(newVal));
     };
   
     return [varRef, set];
   }
   

2. Use the helper in your component or context:

   const [theme, setTheme] = usePersistentVar('appTheme', 'light');
   
   // Read the value
   const currentTheme = theme();
   
   // Update it
   setTheme(currentTheme === 'light' ? 'dark' : 'light');
   

3. Optionally, expose the variable via a React context so all components share the same instance:

   import { ApolloProvider } from '@apollo/client';
   import { ApolloClient, InMemoryCache } from '@apollo/client';
   
   const client = new ApolloClient({
     cache: new InMemoryCache(),
   });
   
   // Wrap your app
   ReactDOM.createRoot(document.getElementById('root')).render(
     <ApolloProvider client={client}>
       <App />
     </ApolloProvider>
   );
   

Things to Keep in Mind

• Only JSON‑serializable data can be stored in localStorage. Functions, class instances, or circular references will break on rehydration.
• LocalStorage is synchronous and limited to roughly 5 MB per origin. If your state grows large, consider IndexedDB or a server‑side store.
• Data in localStorage is visible to any script on the page, so avoid sensitive tokens or PII without encryption.
• Multiple tabs can race on the same key. Listen for the storage event or use BroadcastChannel to keep tabs in sync if needed.

Verification Checklist

1. Render a component that displays the reactive variable.
2. Change the variable via a button and confirm a new value appears in DevTools → Application → Local Storage.
3. Refresh the page; the component should show the persisted value.
4. Try storing a non‑serializable value (e.g., a function) and observe that the variable falls back to the initializer on reload.

Missing Diagnostic Detail

If you need a different persistence strategy (e.g., IndexedDB) or your reactive variable contains non‑serializable data, let me know so I can tailor the advice accordingly.