Guess.js Webpack Plugin

Common errors

• Error: GA_VIEW_ID is required for GuessPlugin configuration.

  cause The `GA` option in `GuessPlugin` was omitted or set to an invalid value, preventing Google Analytics data from being fetched.
  fix Provide a valid Google Analytics View ID to the `GA` property in your `GuessPlugin` configuration: `new GuessPlugin({ GA: 'UA-XXXXX-Y' })`.

• TypeError: guess is not a function

  cause The `guess` function was imported incorrectly (e.g., as a default import or from the wrong path).
  fix Ensure `guess` is imported as a named export from `guess-webpack/api`: `import { guess } from 'guess-webpack/api';`

• Error: Failed to fetch Google Analytics data. Check credentials.

  cause Authentication to the Google Analytics API failed, possibly due to incorrect JWT credentials or issues with OAuth2 setup.
  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.

• Module not found: Error: Can't resolve 'guess-parser'

  cause The `guess-parser` package is used by `GuessPlugin` for automatic route parsing but is not installed as a dependency.
  fix Install `guess-parser` as a development dependency: `npm install --save-dev guess-parser`.

Warnings

• gotcha 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.
  Fix: Always pin to exact versions (e.g., `"guess-webpack": "0.4.22"`) and review release notes carefully before upgrading.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install guess-webpack npm
• yarn add guess-webpack yarn
• pnpm add guess-webpack pnpm

Imports

• GuessPlugin
  wrong:

  const GuessPlugin = require('guess-webpack').default;

  correct:

  import { GuessPlugin } from 'guess-webpack';

  While the README shows CommonJS `require`, modern TypeScript/ESM projects should use named `import`.
• GuessPlugin (CJS)

  const { GuessPlugin } = require('guess-webpack');

  Standard CommonJS import pattern as shown in the README for Node.js environments.
• guess
  wrong:

  import guess from 'guess-webpack/api';

  correct:

  import { guess } from 'guess-webpack/api';

  The `guess` function is a named export from a specific subpath, not a default export.
• parseRoutes
  wrong:

  import { parseRoutes } from 'guess-webpack';

  correct:

  import { parseRoutes } from 'guess-parser';

  Note that `parseRoutes` is imported from the separate `guess-parser` package, not `guess-webpack` directly.

Quickstart

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.

import path from 'path';
import { GuessPlugin } from 'guess-webpack';

// webpack.config.js
// Assumes you have 'webpack' and 'webpack-cli' installed as dev dependencies
// and a 'package.json' initialized.
module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/' // Important for route recognition
  },
  plugins: [
    new GuessPlugin({
      // Replace 'GOOGLE_ANALYTICS_VIEW_ID' with your actual GA View ID
      // For local development, you might mock this or use test data.
      GA: process.env.GOOGLE_ANALYTICS_VIEW_ID ?? 'UA-XXXXX-Y',
      // Example with JWT for server-side auth (optional)
      // jwt: require('./credentials.json'),
      // Example routeProvider for automatic prefetching (requires 'guess-parser')
      // For many React/Vue apps, custom mapping might be needed.
      // For this quickstart, we omit `routeProvider` to keep it simple, 
      // relying on manual `guess()` calls at runtime.
      runtime: {
        delegate: false // Delegate to framework-specific prefetching if available
      }
    })
  ],
  devServer: {
    static: './dist',
    historyApiFallback: true // Important for SPA routing
  }
};

// src/index.js (simplified application entry point)
import { guess } from 'guess-webpack/api';

console.log('Application started.');

// Simulate a route change or initial load
function simulateNavigation(currentRoute = '/') {
  const predictions = guess(currentRoute);
  console.log(`From ${currentRoute}, likely next pages:`, predictions);
  // In a real app, you would use 'predictions' to prefetch bundles
  // For example, fetch(predictions[0].url);
}

// Call on initial load
simulateNavigation();

// Simulate navigation after a delay
setTimeout(() => {
  simulateNavigation('/foo');
}, 3000);

// This quickstart demonstrates configuring the GuessPlugin in webpack
// and using the runtime `guess` function to get predictions for prefetching.