> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/natively-platform/features/service-worker.md).

# Service Worker

## 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.

{% hint style="danger" %}
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](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) or [Google's Workbox Guide](https://developer.chrome.com/docs/workbox/) for best practices on building one.
{% endhint %}

## Prerequisites

{% hint style="success" %}
This feature requires the **Unlimited** or **Lifetime** plan. [See all plans](/getting-started/subscription-plans.md)
{% endhint %}

* 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).

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

## 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**](/natively-platform/appearance/network-screen.md#continual-network-check-feature) under your [Error Screen](/natively-platform/appearance/network-screen.md) 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

<details>

<summary>Resources aren't being cached</summary>

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.

</details>

<details>

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

Confirm that [**Continual Network Check**](/natively-platform/appearance/network-screen.md#continual-network-check-feature) is disabled under your [Error Screen](/natively-platform/appearance/network-screen.md) settings - it overrides cached content by forcing the Error Screen as soon as connectivity drops.

</details>

<details>

<summary>App behaves differently than expected after going offline</summary>

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.

</details>