vite-plugin-inject-sw-assets

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

Changelog

[1.0.2] – 2025-07-05

🛠️ Fixed

• All compiled .js files now include proper .js extensions in ESM import paths
• Fixed ERR_MODULE_NOT_FOUND in Node.js ESM projects

🔧 Added

• Post-build script scripts/fix-extensions.js to rewrite relative imports in dist/**/*.js
• Automatically adds .js extension to relative ESM imports like import './utils/foo' → './utils/foo.js'
• Updated build script in package.json to run the patch after tsc

✅ Improved

• Removed the need for "module": "NodeNext" by post-processing import paths
• Simplified ESM compatibility without changing development imports

<br> <br>