Skip to content

Progressive Web App & Offline Mode

Bifolk works as a Progressive Web App (PWA), which means you can install it like a native app on your device and use key features even without internet connectivity.

Target Audience: Beekeepers working in the field

What is a PWA?

A Progressive Web App runs in your browser but can be installed on your device like a regular app. Benefits include:

  • Install on your device: Add Bifolk to your home screen or desktop
  • Offline access: View cached pages and submit forms without internet
  • Automatic sync: Offline submissions are sent when you're back online
  • Fast loading: Cached assets load instantly

Note

PWA must be enabled by your administrator (see Configuration). In production, HTTPS is required for the service worker to register. On localhost, HTTPS is not required.

Installing Bifolk

On Android (Chrome)

  1. Open Bifolk in Chrome
  2. Tap the menu (three dots) in the top right
  3. Tap Install app or Add to Home Screen
  4. Confirm the installation
  5. Bifolk appears on your home screen as an app

On iOS (Safari)

  1. Open Bifolk in Safari
  2. Tap the Share button (square with arrow)
  3. Scroll down and tap Add to Home Screen
  4. Tap Add
  5. Bifolk appears on your home screen

On Desktop (Chrome/Edge)

  1. Open Bifolk in your browser
  2. Look for the install icon in the address bar (or browser menu)
  3. Click Install
  4. Bifolk opens in its own window

Offline Access

What Works Offline

When you lose internet connectivity, Bifolk provides:

  • Dashboard: Cached version of the Dashboard page
  • Previously visited pages: Any page you visited while online is available from the cache
  • Static assets: CSS, JavaScript, and images are cached
  • Quick notes and form submissions: You can record operations offline using the quick create feature

What Requires Internet

  • Loading pages for the first time (they must be cached first)
  • Viewing data that has not been cached
  • Search functionality
  • Real-time data updates

Offline Form Submissions

When you are in the field without internet, you can use the quick create button to record an inspection. Inspections are the only operation type supported offline, as other types require too many fields to fill in reliably without connectivity.

When you submit an inspection while offline:

  1. The form data is stored locally in your browser (IndexedDB)
  2. A confirmation message appears indicating the submission is queued
  3. When internet connectivity is restored, the data is automatically sent to the server
  4. If a security token has expired, it is refreshed automatically before retrying
  5. Failed submissions are retried up to 3 times with increasing delays

Note

Feeding, treatment, maintenance, and harvest operations are not available when offline. They reappear in the quick create menu as soon as connectivity is restored.

Tip

Visit the app while online before heading to the apiary so that hive data is cached. This allows the offline quick note form to show your hives in the dropdown.

Pending Operations

While offline, a badge in the sidebar shows how many operations are waiting to be synced. When you come back online, they are processed automatically. You also see a notification confirming how many operations were synced successfully.

Caching Strategy

Bifolk uses different caching strategies depending on the content type:

Content Strategy Behavior
HTML pages Network-First Try network, fall back to cached version
Static assets (CSS, JS, images) Cache-First Serve from cache, update in background
Admin pages, authentication Network-Only Never cached for security

Cache Updates

  • The service worker automatically updates when a new version is deployed
  • When you switch organizations, HTML caches are cleared to show correct data
  • When you switch languages, HTML caches are cleared to show the correct language

Organization & Language Switching

The PWA handles organization and language switching correctly:

  • Organization switch: Clears cached HTML pages so the new organization's data is shown
  • Language switch: Clears cached HTML pages so the correct language is displayed
  • Static assets (CSS, JS) are not affected by these switches

Troubleshooting

App Not Installing

  • Verify you are using HTTPS (required in production, not needed on localhost)
  • Check that PWA is enabled in the server configuration (PWA_ENABLED=True)
  • Try clearing your browser cache and reloading

Offline Mode Not Working

  • Visit the pages you want to use offline at least once while connected (pages must be cached first)
  • Check that the service worker is registered (browser developer tools > Application > Service Workers)
  • Try unregistering the service worker and reloading

Pending Operations Not Syncing

  • Verify your internet connection is restored
  • Check the browser console for error messages
  • Operations are retried up to 3 times with increasing delays
  • If operations fail after all retries, they remain in the queue for manual review

What's Next