EN | FR

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.

Why this plugin?

When using 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

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

Usage

In your vite.config.ts file

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)

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:

importScripts('sw-assets.js') 

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

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

Exemple de fichier généré

File dist/sw-assets.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

├── 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