vite-plugin-inject-sw-assets/README.md

A Vite plugin that injects static assets into a custom service worker for use with injectManifest (ideal for Workbox + vite-plugin-pwa setups).

**EN** | [FR](./fr/README.md)

<div>
  <img src="https://browserux.com/img/logos/logo-browserux-inject-sw-assets-300.png" alt="logo vite-plugin-inject-sw-assets"/>
</div>

# BrowserUX Inject SW Assets

> A Vite plugin that automatically injects static assets into a custom service worker (`injectManifest`) for full offline support.

`vite-plugin-inject-sw-assets` is a Vite plugin that injects additional static files into your service worker's precache list. It complements `vite-plugin-pwa` when using the `injectManifest` strategy by ensuring that files like images, fonts, or JSON used only in HTML are properly cached.

[![npm version](https://img.shields.io/npm/v/vite-plugin-inject-sw-assets.svg)](https://www.npmjs.com/package/vite-plugin-inject-sw-assets)
![vite compatibility](https://img.shields.io/badge/Vite-4%2B%20%7C%205%2B%20%7C%206%2B%20%7C%207%2B-646CFF.svg?logo=vite&logoColor=white)

## Why this plugin?

When using [`vite-plugin-pwa`](https://github.com/antfu/vite-plugin-pwa) with the `injectManifest` strategy, the service worker is fully customized. This means the developer is responsible for manually declaring which files should be precached. While Workbox automatically injects JS, CSS, and HTML files referenced by Vite, it **does not include static assets** such as images, fonts, or JSON files that are used only in HTML.

This leads to a common issue:

Images referenced directly in your HTML files (e.g. `<img src="...">`) are **not precached automatically**.

### What this plugin does

- 🔍 Automatically scans the `dist/` output folder for static files at the end of the build
- 🖼️ Detects all files matching configurable extensions (default: `.png`, `.svg`, `.ico`, `.webp`, `.json`)
- 🧼 Skips files already listed in your `manifest.webmanifest` (e.g. PWA icons)
- ⚙️ Generates a JavaScript file that can be imported into your custom service worker

### Benefits

- Automates a commonly forgotten step when using `injectManifest`
- Prevents 404 errors when offline for HTML-embedded images
- Compatible with all Vite + PWA workflows
- Easily customizable (`extensions`, `excludeFromManifest`, etc.)

## Installation

```bash
npm install vite-plugin-inject-sw-assets --save-dev
```

## Usage

### In your `vite.config.ts` file

```js
import { defineConfig } from 'vite'
import { VitePWA } from 'vite-plugin-pwa'
import { globSync } from 'glob';
import injectSWAssets from 'vite-plugin-inject-sw-assets'

export default defineConfig({
    plugins: [
        injectSWAssets({
            extensions: ['png', 'svg', 'json'] // optional
        }),
        VitePWA({
            strategies: 'injectManifest',
            srcDir: 'src',
            filename: 'sw.js',
            manifest: {
                icons: [/* ... */]
            }
        })
    ]
})
```

### Integration in the Service Worker (`sw.js`)

```js
import { precacheAndRoute } from 'workbox-precaching'

// Load injected assets (generated by the plugin)
importScripts('sw-assets.js') 

// Files automatically injected by Workbox
precacheAndRoute(self.__WB_MANIFEST)

// Files injected by the plugin
if (self.__INJECTED_ASSETS__) {
    precacheAndRoute(self.__INJECTED_ASSETS__)
}
```

#### Path considerations

- The path passed to `importScripts()` is relative to the service worker file. So if both `sw.js` and `sw-assets.js` are in `dist/`, just use:

```js
importScripts('sw-assets.js') 
```

- If `sw.js` is inside a subdirectory like `dist/src/`, then use:

```js
importScripts('../sw-assets.js')
```

## Exemple de fichier généré

File `dist/sw-assets.js`:

```js
self.__INJECTED_ASSETS__ = [
    { url: "/images/logo.png", revision: null },
    { url: "/data/data.json", revision: null }
]
```

## Options

| Option                | Type       | Default                                               | Description                                                                                   |
| --------------------- | ---------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `distDir`             | `string`   | `"dist"`                                              | Build output directory to scan for static files to inject                                     |
| `output`              | `string`   | `"sw-assets.js"`                                      | Name of the generated JavaScript file containing the injected assets                         |
| `extensions`          | `string[]` | `['png', 'jpg', 'jpeg', 'svg', 'webp', 'ico', 'json']` | File extensions to include in the injection (e.g. images, JSON)                               |
| `excludeFromManifest` | `boolean`  | `true`                                                | Automatically excludes files already listed in `manifest.webmanifest` (e.g. PWA icons)       |


## Project structure

```bash
├── dist/
├── src/
│   ├── index.ts
│   ├── types.ts
│   └── utils/
│   │   ├── file-scanner.ts
│   │   ├── manifest-utils.ts
│   │   └── sw-assets-writer.ts
├── tsconfig.json
├── package.json
├── README.md
```

## How it works (in short)

- Recursively scans the `dist/` folder
- Filters files by extension (configurable)
- Optionally excludes icons already listed in `manifest.webmanifest`
- Generates a JS file (`sw-assets.js`) to be imported in your `sw.js`

## License

MIT © 2025 [Effeilo](https://github.com/Effeilo)