{"id":15635,"library":"guess-webpack","title":"Guess.js Webpack Plugin","description":"guess-webpack is a Webpack plugin that integrates Guess.js, an analytics-driven approach to improving web performance. It leverages machine learning models built from user behavior data (e.g., Google Analytics) to predict future navigation paths and prefetch JavaScript bundles accordingly. This optimizes application load times by ensuring resources are available before the user explicitly requests them. The current stable version is 0.4.22, indicating it is pre-1.0 and its API may still evolve. Unlike traditional static analysis bundlers, guess-webpack differentiates itself by dynamically adapting prefetching strategies based on real-world user data, aiming for more intelligent and efficient resource delivery.","status":"active","version":"0.4.22","language":"javascript","source_language":"en","source_url":"https://github.com/guess-js/guess","tags":["javascript","bundling","webpack","ml","ai","analytics","recommendation","typescript"],"install":[{"cmd":"npm install guess-webpack","lang":"bash","label":"npm"},{"cmd":"yarn add guess-webpack","lang":"bash","label":"yarn"},{"cmd":"pnpm add guess-webpack","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core peer dependency as it is a webpack plugin. Requires webpack >= 4.37.0.","package":"webpack","optional":false},{"reason":"Recommended for running webpack from the command line, especially with webpack v4 and later.","package":"webpack-cli","optional":true},{"reason":"Used by GuessPlugin for fetching structured data from the Google Analytics API to learn about user navigation patterns.","package":"guess-ga","optional":true},{"reason":"Used by GuessPlugin for parsing applications to create mappings between routes and JavaScript bundles, especially for automatic prefetching.","package":"guess-parser","optional":true}],"imports":[{"note":"While the README shows CommonJS `require`, modern TypeScript/ESM projects should use named `import`.","wrong":"const GuessPlugin = require('guess-webpack').default;","symbol":"GuessPlugin","correct":"import { GuessPlugin } from 'guess-webpack';"},{"note":"Standard CommonJS import pattern as shown in the README for Node.js environments.","symbol":"GuessPlugin (CJS)","correct":"const { GuessPlugin } = require('guess-webpack');"},{"note":"The `guess` function is a named export from a specific subpath, not a default export.","wrong":"import guess from 'guess-webpack/api';","symbol":"guess","correct":"import { guess } from 'guess-webpack/api';"},{"note":"Note that `parseRoutes` is imported from the separate `guess-parser` package, not `guess-webpack` directly.","wrong":"import { parseRoutes } from 'guess-webpack';","symbol":"parseRoutes","correct":"import { parseRoutes } from 'guess-parser';"}],"quickstart":{"code":"import path from 'path';\nimport { GuessPlugin } from 'guess-webpack';\n\n// webpack.config.js\n// Assumes you have 'webpack' and 'webpack-cli' installed as dev dependencies\n// and a 'package.json' initialized.\nmodule.exports = {\n  mode: 'development',\n  entry: './src/index.js',\n  output: {\n    filename: 'bundle.js',\n    path: path.resolve(__dirname, 'dist'),\n    publicPath: '/' // Important for route recognition\n  },\n  plugins: [\n    new GuessPlugin({\n      // Replace 'GOOGLE_ANALYTICS_VIEW_ID' with your actual GA View ID\n      // For local development, you might mock this or use test data.\n      GA: process.env.GOOGLE_ANALYTICS_VIEW_ID ?? 'UA-XXXXX-Y',\n      // Example with JWT for server-side auth (optional)\n      // jwt: require('./credentials.json'),\n      // Example routeProvider for automatic prefetching (requires 'guess-parser')\n      // For many React/Vue apps, custom mapping might be needed.\n      // For this quickstart, we omit `routeProvider` to keep it simple, \n      // relying on manual `guess()` calls at runtime.\n      runtime: {\n        delegate: false // Delegate to framework-specific prefetching if available\n      }\n    })\n  ],\n  devServer: {\n    static: './dist',\n    historyApiFallback: true // Important for SPA routing\n  }\n};\n\n// src/index.js (simplified application entry point)\nimport { guess } from 'guess-webpack/api';\n\nconsole.log('Application started.');\n\n// Simulate a route change or initial load\nfunction simulateNavigation(currentRoute = '/') {\n  const predictions = guess(currentRoute);\n  console.log(`From ${currentRoute}, likely next pages:`, predictions);\n  // In a real app, you would use 'predictions' to prefetch bundles\n  // For example, fetch(predictions[0].url);\n}\n\n// Call on initial load\nsimulateNavigation();\n\n// Simulate navigation after a delay\nsetTimeout(() => {\n  simulateNavigation('/foo');\n}, 3000);\n\n// This quickstart demonstrates configuring the GuessPlugin in webpack\n// and using the runtime `guess` function to get predictions for prefetching.","lang":"typescript","description":"Configures `GuessPlugin` in `webpack.config.js` to enable analytics-driven bundling and demonstrates the runtime usage of the `guess` function for predictive prefetching based on current or specified routes."},"warnings":[{"fix":"Always pin to exact versions (e.g., `\"guess-webpack\": \"0.4.22\"`) and review release notes carefully before upgrading.","message":"The package version 0.4.22 indicates that `guess-webpack` is in pre-1.0 development. APIs might not be fully stable and could introduce breaking changes in minor versions.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure `GA: 'YOUR_GOOGLE_ANALYTICS_VIEW_ID'` is correctly set in `GuessPlugin` configuration. Validate the View ID using Google Analytics Query Explorer. Consider using JWT authentication for CI/CD environments instead of OAuth2. Add `credentials.json` to `.gitignore` for security.","message":"Providing Google Analytics data is crucial. The `GA` property in `GuessPlugin` configuration requires a valid Google Analytics View ID. Incorrect or missing IDs will prevent data fetching and model generation.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"For complex React/Vue applications, you might need to implement a custom `routeProvider` in the `GuessPlugin` configuration or manually define the route-to-bundle mapping.","message":"The `parseRoutes` function from `guess-parser` (used for automatic prefetching) may not accurately map routes to bundles in highly dynamic applications, particularly those built with certain React or Vue patterns.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Ensure your project uses webpack v4 or higher (recommended v5+) and `webpack-cli`. Consult webpack migration guides for `v3` to `v4` and `v4` to `v5` to update your webpack configuration.","message":"webpack 4 introduced significant breaking changes compared to webpack 3, including the move of CLI to `webpack-cli`, removal of `CommonsChunkPlugin`, and changes to `import()` behavior for CommonJS modules. `guess-webpack` is designed for modern webpack versions.","severity":"breaking","affected_versions":"webpack <4"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Provide a valid Google Analytics View ID to the `GA` property in your `GuessPlugin` configuration: `new GuessPlugin({ GA: 'UA-XXXXX-Y' })`.","cause":"The `GA` option in `GuessPlugin` was omitted or set to an invalid value, preventing Google Analytics data from being fetched.","error":"Error: GA_VIEW_ID is required for GuessPlugin configuration."},{"fix":"Ensure `guess` is imported as a named export from `guess-webpack/api`: `import { guess } from 'guess-webpack/api';`","cause":"The `guess` function was imported incorrectly (e.g., as a default import or from the wrong path).","error":"TypeError: guess is not a function"},{"fix":"Verify your `jwt` credentials file (e.g., `credentials.json`) is correct and accessible, or ensure your OAuth2 authentication flow is properly configured and authorized.","cause":"Authentication to the Google Analytics API failed, possibly due to incorrect JWT credentials or issues with OAuth2 setup.","error":"Error: Failed to fetch Google Analytics data. Check credentials."},{"fix":"Install `guess-parser` as a development dependency: `npm install --save-dev guess-parser`.","cause":"The `guess-parser` package is used by `GuessPlugin` for automatic route parsing but is not installed as a dependency.","error":"Module not found: Error: Can't resolve 'guess-parser'"}],"ecosystem":"npm"}