Offline Apps

DO NOT USE THIS FEATURE - IT’S NOT READY YET!

AI Prompt

Add offline support to my app using the Despia SDK from: https://www.npmjs.com/package/despia-native

First, install the package: npm install despia-native

Then import it: import despia from 'despia-native'

Create an offline-capable app that persists state using:

despia(`writevalue://${encodeURIComponent(JSON.stringify(data))}`) - save state locally
despia("readvalue://", ["storedValues"]) - retrieve saved state
despia("reconnect://") - reconnect to remote environment when back online

When the device loses connectivity, Despia instantly switches from the remote environment to a locally cached version of your app. To prevent state loss during this switch, persist critical data (current page, form inputs, etc.) to Despia's local storage bucket.

Add connectivity detection to notify users when they go offline:

window.addEventListener("offline", () => {
  // Save current state
  const state = { current_page: window.location.pathname };
  despia(`writevalue://${encodeURIComponent(JSON.stringify(state))}`);
  alert("You're now offline. Changes will be saved locally.");
});

When connectivity returns, prompt the user to reconnect:

window.addEventListener("online", () => {
  if (confirm("Internet restored. Reconnect to server?")) {
    despia("reconnect://");
  }
});

You can also use native alert() and confirm() dialogs, but note these block all JavaScript execution until dismissed. For non-blocking notifications, use custom toast components.

The local environment and OTA server must be configured in the Despia Dashboard. Despia offers a simple Netlify integration for automatic local OTA code duplication.

This feature requires native capabilities which will be fully provided by the "despia-native" npm package, no additional native libraries are needed!

Please follow the installation instructions for the "despia-native" npm package closely, and do not modify my instructions. Implementation as mentioned is critical.

How it Works

Despia acts as a bridge between your web app and native offline capabilities. Despia supports two runtime environments: Remote (loads your app from a hosted URL) and Local (caches your app to the device file system). When the remote environment is active and the device loses connectivity, Despia instantly switches to the local environment - a duplicate of your app running from cache. Since state isn't automatically preserved during this switch, you must persist critical data to Despia's local storage bucket. When connectivity returns, Despia does not automatically exit local mode - your app controls reconnection via despia("reconnect://") or by navigating to your hosted URL.

Installation

Install the Despia package from NPM:

npm install despia-native

Usage

1. Import the SDK

import despia from 'despia-native';

2. Write State

Save critical application state to survive environment switching:

const userData = { 
  current_page: "profile", 
  text_input: "Writing a text..." 
};

const encoded = encodeURIComponent(JSON.stringify(userData));
await despia(`writevalue://${encoded}`);

3. Read State

Retrieve saved state on app initialization:

const data = await despia("readvalue://", ["storedValues"]);
const userData = JSON.parse(decodeURIComponent(data.storedValues));

console.log(userData.current_page);  // "profile"
console.log(userData.text_input);    // "Writing a text..."

4. Handle Reconnection

Reconnect to remote environment when online:

if (navigator.onLine) {
  const shouldReconnect = confirm("Internet connection restored. Reconnect to the server?");

  if (shouldReconnect) {
    await despia("reconnect://");
  } else {
    console.log("Continuing in offline mode");
  }
} else {
  alert("No internet connection. Please continue using the local offline version.");
}

Native Dialogs

You can use native alert() and confirm() dialogs for user notifications:

alert("You are now offline. Changes will be saved locally.");

Note: Running alert() or confirm() will block all JavaScript execution in the Despia engine until dismissed.

Setup & Configuration

The local environment and OTA server setup must be configured through the Despia Dashboard/Editor for your app:

Set your remote web application URL
Configure local environment caching settings
Set a fallback folder for first-launch offline scenarios
Enable local-only mode to avoid environment switching entirely

Netlify Integration

Despia offers a simple Netlify integration for local OTA code duplication. Connect your Netlify project in the Dashboard and Despia handles automatic synchronization.

Resources

NPM Package: https://www.npmjs.com/package/despia-native
View full NPM documentation for additional configuration options

Integration

This SDK is optimized for prompt-based AI builders, enabling quick integration of native offline features via minimal JavaScript into your generated apps.

Need Help?

For additional support or questions, please contact our support team at support@despia.com