# CDN and Versions

{% hint style="info" %}
**Note**: This page covers advanced Workbox configuration. Most applications should use the [default configuration documented in the Workbox README](/1.4.x/the-service-worker/workbox.md#cdn-vs-local-installation).
{% endhint %}

## Default Configuration

The bundle ships with Workbox **7.3.0** (released October 2024) and serves all files locally from your application server. This provides:

* Faster loading (same-origin)
* Offline availability immediately
* No external dependencies
* Better privacy
* Controlled updates

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    serviceworker:
        workbox:
            use_cdn: false  # Default
            version: "7.3.0"  # Default
```

{% endcode %}

## Available Versions

The bundle includes these Workbox versions locally:

* **7.3.0** (default, recommended)
* **7.0.0** (for compatibility if needed)

## Using a CDN

For quick prototyping or bandwidth considerations, you can load Workbox from a CDN:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    serviceworker:
        enabled: true
        src: "sw.js"
        workbox:
            use_cdn: true
            version: "7.3.0"
```

{% endcode %}

When `use_cdn: true`, Workbox files are loaded from `https://storage.googleapis.com/workbox-cdn/releases/{version}/`.

### CDN Pros

* **No local storage**: Workbox files not bundled with your app
* **Shared cache**: Users may already have Workbox cached from other sites
* **Always latest**: Can easily switch versions
* **Reduced deploy size**: Slightly smaller deployment

### CDN Cons

* **External dependency**: Requires Google's CDN to be available
* **Network request**: Adds latency on first load
* **Privacy**: Third-party request (though Google doesn't track via Workbox CDN)
* **Offline delay**: Service worker can't work until Workbox loads
* **Version risk**: CDN outages affect your app

{% hint style="warning" %}
**Production Recommendation**: Use local installation (`use_cdn: false`) for production applications. The benefits of local hosting far outweigh the small bandwidth savings of a CDN.
{% endhint %}

## Custom Versions

You can specify any Workbox version when using the CDN:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    serviceworker:
        workbox:
            use_cdn: true
            version: "6.5.4"  # Older version
```

{% endcode %}

### Version Selection Guidelines

**Use 7.3.0 (default)** when:

* Starting a new project
* No specific compatibility requirements
* Want the latest features and fixes

**Use 7.0.0** when:

* Need stability over new features
* Specific compatibility requirements
* Team has testing/docs for 7.0.0

**Use 6.x** when:

* Legacy project already using Workbox 6.x
* Breaking changes in 7.x affect your application
* Need to maintain compatibility with older code

{% hint style="danger" %}
**Major Version Upgrades**: Workbox 7.x includes breaking changes from 6.x. Review the [Workbox migration guide](https://developer.chrome.com/docs/workbox/migration/migrate-from-v6/) before upgrading.
{% endhint %}

## Complete Configuration Examples

### Local Installation (Recommended)

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    serviceworker:
        enabled: true
        src: "sw.js"
        workbox:
            enabled: true
            use_cdn: false          # Local files (default)
            version: "7.3.0"        # Latest bundled version
            workbox_public_url: "/workbox"  # Where Workbox is served
            idb_public_url: "/idb"          # Where IndexedDB lib is served
```

{% endcode %}

### CDN Installation

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    serviceworker:
        enabled: true
        src: "sw.js"
        workbox:
            enabled: true
            use_cdn: true           # Load from Google CDN
            version: "7.3.0"        # Version to load
```

{% endcode %}

### Legacy Version with CDN

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    serviceworker:
        enabled: true
        src: "sw.js"
        workbox:
            enabled: true
            use_cdn: true
            version: "6.5.4"        # Older version for compatibility
```

{% endcode %}

## Custom Public URLs (Local Only)

When using local installation, customize where Workbox files are served:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    serviceworker:
        workbox:
            use_cdn: false
            workbox_public_url: "/assets/workbox"
            idb_public_url: "/assets/idb"
```

{% endcode %}

This is useful when:

* Organizing assets by type
* Complying with specific URL structures
* Integrating with CDN configurations

## Checking Your Configuration

To verify which Workbox version and source is being used:

1. Open DevTools (F12)
2. Go to **Application** → **Service Workers**
3. View service worker source
4. Look for `importScripts()` calls at the top

**Local installation**:

```javascript
importScripts('/workbox/workbox-sw.js');
```

**CDN installation**:

```javascript
importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.3.0/workbox-sw.js');
```

## Version Update Process

When updating Workbox versions:

1. **Review changelog**: Check [Workbox releases](https://github.com/GoogleChrome/workbox/releases) for breaking changes
2. **Update configuration**: Change `version` in `pwa.yaml`
3. **Clear caches**: Clear browser caches during testing
4. **Test thoroughly**: Test all caching strategies and offline functionality
5. **Monitor**: Watch for errors after deployment

## Troubleshooting

**Workbox not loading?**

* Check CDN availability if `use_cdn: true`
* Verify `version` is correct and available
* Check browser console for import errors
* Ensure service worker is registered

**Using CDN but want to switch to local?**

```yaml
workbox:
    use_cdn: false  # Switch to local
    version: "7.3.0"
```

Then clear caches and re-register service worker.

**Using local but Workbox not found?**

* Verify bundle provides the version you specified
* Check `workbox_public_url` is accessible
* Look for 404 errors in Network tab

{% hint style="success" %}
**Best Practice**: Start with local installation using the default version. Only use CDN for quick prototyping or specific use cases where bandwidth is critical and reliability of an external CDN is acceptable.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pwa.spomky-labs.com/1.4.x/the-service-worker/workbox/cdn-and-versions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.