{"id":15738,"library":"offline-bundler-plugin","title":"Offline Bundler Plugin","description":"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.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install offline-bundler-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add offline-bundler-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add offline-bundler-plugin","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the CommonJS `require` statement typically used in Webpack configuration files, where the plugin is instantiated with `new`.","wrong":"import { OfflinePackagePlugin } from 'offline-bundler-plugin';","symbol":"OfflinePackagePlugin","correct":"const OfflinePackagePlugin = require('offline-bundler-plugin');"},{"note":"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`).","wrong":"const OfflinePackagePlugin = require('offline-bundler-plugin/vite');","symbol":"OfflinePackagePlugin","correct":"import OfflinePackagePlugin from 'offline-bundler-plugin/vite';"}],"quickstart":{"code":"// For Webpack: webpack.config.js (or similar, requiring commonjs)\nconst OfflinePackagePluginWebpack = require('offline-bundler-plugin');\nconst path = require('path');\nconst HtmlWebpackPlugin = require('html-webpack-plugin');\n\nmodule.exports = {\n  mode: 'production',\n  entry: './src/index.js',\n  output: {\n    filename: '[name].[contenthash].js',\n    path: path.resolve(__dirname, 'dist-webpack'),\n  },\n  plugins: [\n    new HtmlWebpackPlugin({\n      template: './src/index.html',\n      filename: 'index.html',\n    }),\n    new OfflinePackagePluginWebpack({\n      packageNameKey: 'packageId',\n      packageNameValue: 'my-app-webpack',\n      version: 1,\n      baseUrl: 'http://localhost:8080/', // Replace with your actual deployment base URL\n      fileTypes: ['html', 'js', 'css', 'png'],\n      folderName: 'offline-bundle-webpack',\n    }),\n  ],\n};\n\n// For Vite: vite.config.ts (or similar, using ESM)\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react'; // Example framework plugin\nimport OfflinePackagePluginVite from 'offline-bundler-plugin/vite';\n\nexport default defineConfig({\n  plugins: [\n    react(),\n    OfflinePackagePluginVite({\n      packageNameKey: 'packageId',\n      packageNameValue: 'my-app-vite',\n      version: 1,\n      baseUrl: 'http://localhost:3000/', // Replace with your actual deployment base URL\n      fileTypes: ['html', 'js', 'css', 'png'],\n      folderName: 'offline-bundle-vite',\n    }),\n  ],\n  build: {\n    outDir: 'dist-vite',\n  },\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"For Vite: `plugins: [OfflinePackagePlugin(...)]`. For Webpack: `plugins: [new OfflinePackagePlugin(...)]`.","message":"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`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `require('offline-bundler-plugin')` (CommonJS) is used for Webpack configurations, and `import OfflinePackagePlugin from 'offline-bundler-plugin/vite'` (ESM) for Vite configurations.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Remove the `new` keyword when using the plugin in Vite. Correct usage: `OfflinePackagePlugin({...options})`.","cause":"The Vite plugin entry point exports a function, not a class. It was incorrectly invoked with the `new` keyword.","error":"TypeError: OfflinePackagePlugin is not a constructor"},{"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.","cause":"Incorrect import path used in a Webpack configuration, or the package was not installed.","error":"Error: Cannot find module 'offline-bundler-plugin/vite'"},{"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.","cause":"Incorrect import path used in a Vite configuration, or the package was not installed.","error":"Error: Cannot find module 'offline-bundler-plugin'"}],"ecosystem":"npm"}