🚀Service Worker

Cache resources locally on the device to speed up loading and enable offline access.

What is Service Worker?

Service Worker Support lets your app cache specific resources and data directly on the user's device. Once configured, previously loaded content is served from the local cache instead of the network, which speeds up app loading and allows parts of your app to remain usable even when the device is offline.

Natively provides the environment for the Service Worker to run inside the mobile app - the caching logic itself and the service-worker.js file must already be implemented and active on your website. We recommend the official MDN Web Docs: Service Worker API or Google's Workbox Guide for best practices on building one.

Prerequisites

This feature requires the Unlimited or Lifetime plan. See all plans

• A working Service Worker (service-worker.js) already implemented and active on your website.

Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to Features > Service Worker.

2. Toggle the feature to Enabled.

3. Under Domains, add the domains the Service Worker is allowed to cache resources from (e.g. example.com, cdn.example.com). You can add up to 10 hosts.

4. Click Save.

5. Rebuild your app(s).

You must rebuild your app for these changes to take effect.

How to use

Enabling this feature disables the default Network Check

When Service Worker is enabled, Natively's default network connectivity check is automatically disabled. Your website is now responsible for its own fallback UI for when there's no network connection and no cached data available to serve.

Disable Continual Network Check if you want true offline access

If your goal is to let users access the app while offline, you must also disable Continual Network Check under your Error Screen settings. If left enabled, Natively will show the native Error Screen as soon as the device goes offline - before your cached content ever gets a chance to load - blocking the exact experience the Service Worker is meant to provide.

Only whitelisted hosts are cached

Resources are only cached from domains listed under the Service Worker feature Domains configuration. If your app loads assets from a CDN or a separate subdomain, make sure to add each one - anything not listed will always be fetched from the network.

For iOS, list every domain your app might redirect to - not just your own

On iOS, Service Worker restricts navigation to domains listed under Domains - any redirect to a domain not on that list will be blocked by the OS. This includes third-party domains you don't own but redirect to as part of a normal flow, such as a payment provider.

Troubleshooting

Resources aren't being cached

Confirm the resource's domain is listed under Trusted Hosts in the Natively Dashboard, and that your website's service-worker.js is actually registering and caching that resource - Natively only provides the runtime, not the caching logic itself.

The app shows the Error Screen immediately when offline, even though the Service Worker is enabled

Confirm that Continual Network Check is disabled under your Error Screen settings - it overrides cached content by forcing the Error Screen as soon as connectivity drops.

App behaves differently than expected after going offline

Since your website's fallback UI is now responsible for the no-network, no-cache case (the default Network Check is disabled once the Service Worker is on), verify that the fallback UI is implemented and tested on your website directly.