# Use the JavaScript Service Worker SDK

<!--Page Type: Explanation. Although, in its current form, it is a mix of explanation and how-to guide.-->

<!--Documentation Rating: 
Technical Accuracy Score: 100
Comprehensibility Score: 80
Overall Score: 92

This documentation has no technical accuracy issues. However, it could be improved in terms of comprehensibility by separating the content into distinct Explanation and How-To Guide sections, which would align better with Diátaxis principles.-->

<!--Table of Contents:
- Introduction
- Installation
- Usage in Chrome Extensions
- Usage in Serverless Runtimes
  - Cloudflare Worker
  - Vercel Edge-->

This guide explains how to use the JavaScript [service worker SDK](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker) in browser extensions and serverless runtimes.

{{< version-badge registry="npm" package="@rudderstack/analytics-js-service-worker" fallback="3.3.11" href="https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker" >}}

## Overview

The JavaScript service worker SDK brings RudderStack's analytics capabilities to environments where the standard browser JavaScript SDK cannot operate. This specialized SDK targets non-browser contexts that require background processing and offline functionality.

{{< info >}}
This SDK exposes the same interface and applicable features as RudderStack's [Node.js SDK](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-node-sdk/).
{{< /info >}}

Some key features of the service worker SDK are:

- **Browser extension compatibility**: You can integrate analytics into [Chrome extensions](#usage-in-chrome-extensions) using manifest v3, supporting both content scripts and background scripts.
- **Serverless runtime support**: The SDK works seamlessly in [serverless environments](#usage-in-serverless-runtimes) like Cloudflare Workers and Vercel Edge functions.
- **Background processing**: Service workers run independently of web pages, enabling reliable data collection even when users navigate away, and features like offline support and push notifications.

## Install the service worker package

1. Run the following command to install the service worker package:

```bash
npm install @rudderstack/analytics-js-service-worker --save
```

2. Run the following snippet and use the exported object throughout your project:

```javascript
import { Analytics } from '@rudderstack/analytics-js-service-worker';

const rudderClient = new Analytics('<WRITE_KEY>', '<DATA_PLANE_URL>/v1/batch');
```

{{< warning >}}
This NPM module is meant to be used only in non-browser environments. To integrate RudderStack with your Node.js apps, RudderStack recommends using the [Node.js SDK](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-node-sdk/) instead.

Note that the APIs are the same in both the cases.
{{< /warning >}}

## Usage in Chrome extensions

You can use the JavaScript SDK in Chrome extensions with the manifest v3 as:

- [Content script]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/service-worker/usage-in-chrome-extensions.md#content-script" >}}) (via the JavaScript SDK package), OR
- [Background script]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/service-worker/usage-in-chrome-extensions.md#background-script" >}}) (via [JavaScript service worker SDK](https://www.npmjs.com/package/@rudderstack/analytics-js-service-worker)).

See the [Usage in Chrome Extensions]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/service-worker/usage-in-chrome-extensions.md" >}}) for more information.

## Usage in serverless runtimes

You can use the JavaScript service worker SDK in serverless runtimes like Cloudflare workers or Vercel Edge functions.

### Cloudflare worker

To use the JavaScript SDK service worker in Cloudflare workers:

1. Start with the [Cloudflare worker sample](https://developers.cloudflare.com/workers/get-started/guide/).
2. Integrate the SDK in the `worker.js` file:

```javascript
import { Analytics } from '@rudderstack/analytics-js-service-worker';

const rudderClient = new Analytics(
  "<WRITE_KEY>",
  "<DATA_PLANE_URL>/v1/batch",
  {
    flushAt: 1
  }
);
```

3. Use the JavaScript SDK within the `fetch` methods with promisified flush:

```javascript
const flush = () => new Promise((resolve) => rudderClient.flush(resolve));

rudderClient.track({
  userId: '123456',
  event: 'test cloudflare worker',
  properties: {
    data: {
      url: 'test cloudflare worker',
    },
  },
});

await flush();
```

For more information, see this [sample implementation](https://github.com/rudderlabs/rudder-sdk-js/tree/develop/examples/serverless/cloudflare-worker).

### Vercel Edge

To use the JavaScript SDK service worker in Vercel Edge functions:

1. Start with the [Vercel Edge function sample](https://vercel.com/docs/functions/edge-functions/quickstart).
2. Integrate the SDK in the `app/api/edge-function-sample/route.ts` file:

```javascript
import { Analytics } from '@rudderstack/analytics-js-service-worker';

const rudderClient = new Analytics(
  "<WRITE_KEY>",
  "<DATA_PLANE_URL>/v1/batch",
  {
    flushAt: 1
  }
);
```

3. Use the JavaScript SDK within the `fetch` methods as usual:

```javascript
rudderClient.track({
  userId: '123456',
  event: 'test vercel edge worker',
  properties: {
    data: {
      url: 'test vercel edge worker',
    },
  }
});
```

For more information, see this [sample implementation](https://github.com/rudderlabs/rudder-sdk-js/tree/develop/examples/serverless/vercel-edge).

<br />