Offline Bundler Plugin

1.0.3 · active · verified Tue Apr 21

The `offline-bundler-plugin` is a JavaScript/TypeScript utility designed to prepare web applications for offline access. It automates the process of compressing static assets (including JavaScript, CSS, images, and HTML) into a single zip archive and simultaneously generates a resource mapping JSON file. This manifest maps remote URLs of assets to their corresponding local paths within the generated bundle, facilitating efficient offline caching and retrieval. Currently at version 1.0.3, the plugin boasts compatibility with both Webpack and Vite (including UniApp environments), offering broad utility across modern frontend build setups. Its key differentiator lies in its dual-bundler support and its specialized focus on creating structured resource manifests, which goes beyond simple asset compression to enable robust offline-first strategies.

Common errors

```
TypeError: OfflinePackagePlugin is not a constructor
```
cause The Vite plugin entry point exports a function, not a class. It was incorrectly invoked with the `new` keyword.

fix Remove the `new` keyword when using the plugin in Vite. Correct usage: `OfflinePackagePlugin({...options})`.
```
Error: Cannot find module 'offline-bundler-plugin/vite'
```
cause Incorrect import path used in a Webpack configuration, or the package was not installed.

fix For Webpack, use `require('offline-bundler-plugin')`. For Vite, ensure `import OfflinePackagePlugin from 'offline-bundler-plugin/vite'` and that `offline-bundler-plugin` is installed as a dev dependency.
```
Error: Cannot find module 'offline-bundler-plugin'
```
cause Incorrect import path used in a Vite configuration, or the package was not installed.

fix For Vite, use `import OfflinePackagePlugin from 'offline-bundler-plugin/vite'`. For Webpack, ensure `require('offline-bundler-plugin')` and that `offline-bundler-plugin` is installed as a dev dependency.

Warnings

breaking When integrating `offline-bundler-plugin` into a Vite project, the plugin function must be invoked directly, without the `new` keyword. This contrasts with its usage in Webpack, where `new` is required to instantiate the plugin class. Failure to omit `new` in Vite configurations will result in a `TypeError`.
Fix: For Vite: `plugins: [OfflinePackagePlugin(...)]`. For Webpack: `plugins: [new OfflinePackagePlugin(...)]`.
gotcha The plugin exposes different entry points for Webpack and Vite. Attempting to use the Webpack-specific import path (`offline-bundler-plugin`) in a Vite configuration, or vice-versa with (`offline-bundler-plugin/vite`), will lead to module resolution errors or incorrect plugin behavior.
Fix: Ensure `require('offline-bundler-plugin')` (CommonJS) is used for Webpack configurations, and `import OfflinePackagePlugin from 'offline-bundler-plugin/vite'` (ESM) for Vite configurations.
gotcha Webpack configuration files are typically CommonJS modules (`require` syntax), while Vite configurations commonly use ESM (`import` syntax). Mixing these module systems without proper transpilation or configuration can cause runtime errors during the build process.
Fix: Adhere to the standard module system for each bundler: `const MyPlugin = require('my-plugin')` for Webpack and `import MyPlugin from 'my-plugin'` for Vite. If using TypeScript with Webpack, ensure your `tsconfig.json` targets `CommonJS` or uses dynamic imports.

Install

npm install offline-bundler-plugin npm
yarn add offline-bundler-plugin yarn
pnpm add offline-bundler-plugin pnpm

Imports

OfflinePackagePlugin
wrong:
```
import { OfflinePackagePlugin } from 'offline-bundler-plugin';
```
correct:
```
const OfflinePackagePlugin = require('offline-bundler-plugin');
```
This is the CommonJS `require` statement typically used in Webpack configuration files, where the plugin is instantiated with `new`.
OfflinePackagePlugin
wrong:
```
const OfflinePackagePlugin = require('offline-bundler-plugin/vite');
```
correct:
```
import OfflinePackagePlugin from 'offline-bundler-plugin/vite';
```
This is the ESM `import` for Vite projects. The plugin function is a default export from the `/vite` entry point and should be called directly (without `new`).

Quickstart

This quickstart demonstrates how to configure `offline-bundler-plugin` for both Webpack and Vite projects, highlighting the distinct import and instantiation patterns for each bundler. It shows basic configuration options for bundling static assets into a zip with a resource mapping JSON.

// For Webpack: webpack.config.js (or similar, requiring commonjs)
const OfflinePackagePluginWebpack = require('offline-bundler-plugin');
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    filename: '[name].[contenthash].js',
    path: path.resolve(__dirname, 'dist-webpack'),
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './src/index.html',
      filename: 'index.html',
    }),
    new OfflinePackagePluginWebpack({
      packageNameKey: 'packageId',
      packageNameValue: 'my-app-webpack',
      version: 1,
      baseUrl: 'http://localhost:8080/', // Replace with your actual deployment base URL
      fileTypes: ['html', 'js', 'css', 'png'],
      folderName: 'offline-bundle-webpack',
    }),
  ],
};

// For Vite: vite.config.ts (or similar, using ESM)
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react'; // Example framework plugin
import OfflinePackagePluginVite from 'offline-bundler-plugin/vite';

export default defineConfig({
  plugins: [
    react(),
    OfflinePackagePluginVite({
      packageNameKey: 'packageId',
      packageNameValue: 'my-app-vite',
      version: 1,
      baseUrl: 'http://localhost:3000/', // Replace with your actual deployment base URL
      fileTypes: ['html', 'js', 'css', 'png'],
      folderName: 'offline-bundle-vite',
    }),
  ],
  build: {
    outDir: 'dist-vite',
  },
});

view raw JSON →