Google Maps V3 Utility Libraries (Community Fork)

Common errors

• TypeError: google.maps.MarkerClusterer is not a constructor

  cause The Google Maps API global object (`google`) is not loaded or the MarkerClusterer utility is not correctly imported and attached to the `google.maps` namespace.
  fix Ensure the Google Maps JavaScript API script tag is loaded before your application code, and that you are importing `MarkerClusterer` directly from the package: `const MarkerClusterer = require('googlemaps-v3-utility-library-latest');`

• ReferenceError: google is not defined

  cause The Google Maps JavaScript API has not been loaded into the browser environment.
  fix Make sure to include the Google Maps JavaScript API script tag in your HTML `head` or `body` with your API key and `callback` parameter, before any code that attempts to use the `google` object. Example: `<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"></script>`

• Error: Cannot find module 'googlemaps-v3-utility-library-latest/lib/InfoBox'

  cause Incorrect path specified for a utility library or the file does not exist at the expected location after installation.
  fix Double-check the exact casing and path for the desired utility library. Ensure the package is correctly installed via `npm i`. The `/lib` directory contains most individual utilities.

Warnings

• breaking This specific `googlemaps-v3-utility-library-latest` package reflects updates from 2018. It may not be fully compatible with newer versions of the Google Maps JavaScript API (e.g., v3.40+ or changes after 2018), potentially leading to unexpected behavior or breakage.
  Fix: Review the official Google Maps v3-utility-library for more current alternatives or be prepared to fork and adapt the code for newer API versions. Consider using `@googlemaps/markerclusterer` from the official Google Maps organization for a maintained MarkerClusterer.
• deprecated The 'Google Earth API for Google Maps v3' utility included in this collection is explicitly marked as deprecated within the package's own README. Using it may lead to errors or unsupported functionality.
  Fix: Avoid using the deprecated Google Earth API integration. Look for modern alternatives for 3D globe visualization if needed, potentially outside the Google Maps API context.
• gotcha This package is primarily designed for CommonJS/UMD environments. Direct ESM `import` statements may require bundler configuration or specific import paths (e.g., `import * as pkg from 'package'`) to resolve correctly, especially if relying on Node.js module resolution.
  Fix: When using in a modern ESM project, ensure your bundler (Webpack, Rollup, Vite) is configured to handle CommonJS modules. For Node.js, consider dynamic `import()` or stick to `require()` if feasible.
• gotcha The package name `googlemaps-v3-utility-library-latest` can be misleading. While it implies 'latest', its contents are from 2018. Relying on this package for 'latest' features or bug fixes from the Google Maps API can lead to outdated functionality.
  Fix: Always verify the actual last update date and maintenance status of libraries. For the most up-to-date Google Maps utilities, consult the official Google Maps Platform documentation and packages from `@googlemaps`.
• gotcha The project's GitHub link in the README (github.com/nblavoie/v3-utility-library) appears to be broken or redirects. Support is directed to the main Google Maps GitHub repository, implying this specific npm package might not have dedicated support channels.
  Fix: Be aware that this package might not receive direct issue support or updates. Consider migrating to officially maintained libraries if active support is crucial for your project.

Install

• npm install googlemaps-v3-utility-library-latest npm
• yarn add googlemaps-v3-utility-library-latest yarn
• pnpm add googlemaps-v3-utility-library-latest pnpm

Imports

• MarkerClusterer
  wrong:

  import { MarkerClusterer } from 'googlemaps-v3-utility-library-latest';
  // Or (incorrect path):
  import MarkerClusterer from 'googlemaps-v3-utility-library-latest/markerclusterer';
  

  correct:

  import MarkerClusterer from 'googlemaps-v3-utility-library-latest';
  // Or for CommonJS:
  const MarkerClusterer = require('googlemaps-v3-utility-library-latest');

  The `googlemaps-v3-utility-library-latest` package's main entry point directly exports the MarkerClusterer class. It is a default export for ESM purposes, but often consumed via CommonJS `require`.
• InfoBox
  wrong:

  import { InfoBox } from 'googlemaps-v3-utility-library-latest';
  // Or (incorrect path):
  import InfoBox from 'googlemaps-v3-utility-library-latest/InfoBox';

  correct:

  import InfoBox from 'googlemaps-v3-utility-library-latest/lib/InfoBox';
  // Or for CommonJS:
  const InfoBox = require('googlemaps-v3-utility-library-latest/lib/InfoBox');

  Other utility libraries like InfoBox are located in the `lib` subdirectory and must be imported via their specific path within the package. These are typically default exports for their respective modules.
• KeyDragZoom
  wrong:

  import { KeyDragZoom } from 'googlemaps-v3-utility-library-latest';

  correct:

  import KeyDragZoom from 'googlemaps-v3-utility-library-latest/lib/KeyDragZoom';
  // Or for CommonJS:
  const KeyDragZoom = require('googlemaps-v3-utility-library-latest/lib/KeyDragZoom');

  Similar to InfoBox, utilities other than MarkerClusterer are found in the `lib` folder. Always specify the full path to the desired utility module.

Quickstart

Demonstrates initializing a Google Map and adding a MarkerClusterer with random markers, using the package's primary export. Includes conditional loading for the Google Maps API.

import MarkerClusterer from 'googlemaps-v3-utility-library-latest';

function initMap() {
  const map = new google.maps.Map(document.getElementById('map'), {
    zoom: 3,
    center: { lat: -28.024, lng: 140.887 },
    mapId: 'DEMO_MAP_ID' // Replace with your Map ID
  });

  const markers = [];
  // Create some random markers
  for (let i = 0; i < 100; i++) {
    const latLng = new google.maps.LatLng(
      -28.024 + Math.random() * 10,
      140.887 + Math.random() * 10
    );
    markers.push(new google.maps.Marker({
      position: latLng
    }));
  }

  // Add a marker clusterer to the map.
  new MarkerClusterer(map, markers, {
    imagePath: 'https://developers.google.com/maps/documentation/javascript/examples/markerclusterer/m'
  });
}

// Ensure the global `google` object is available (e.g., via script tag in HTML)
// For demonstration purposes, if not using a global callback, call directly:
// This assumes the Google Maps API script is loaded globally and defines `google`
// For a real application, follow Google's recommended async loading with a callback.
window.addEventListener('DOMContentLoaded', () => {
  if (typeof google !== 'undefined' && google.maps) {
    initMap();
  } else {
    console.warn('Google Maps API not loaded. Ensure the script tag is present.');
    // You might want to dynamically load it here or handle the missing global differently
    const script = document.createElement('script');
    script.src = `https://maps.googleapis.com/maps/api/js?key=${process.env.GOOGLE_MAPS_API_KEY ?? 'YOUR_API_KEY'}&callback=initMap`;
    script.async = true;
    document.head.appendChild(script);
    window.initMap = initMap; // Attach to window for the callback
  }
});