GMaps.js Deployment & Usage Guide

Prerequisites

• Node.js (v12+) and npm — Required only if building from source
• Google Maps JavaScript API Key — Required for production use (obtain from Google Cloud Console)
• Modern web browser with JavaScript enabled
• Git — For cloning the repository

Installation

Option 1: Direct Download (Simplest)

Download gmaps.min.js from the repository and include it in your project:

curl -O https://raw.githubusercontent.com/HPNeo/gmaps/master/gmaps.min.js

Option 2: Build from Source

git clone https://github.com/HPNeo/gmaps.git
cd gmaps
npm install
grunt

Built files will be available in the root directory (gmaps.js, gmaps.min.js).

Option 3: Module Loaders

The library supports AMD, CommonJS, and browser globals (UMD).

NPM (if migrating to NPM per Issue #404):

npm install gmaps

Configuration

1. Google Maps API Setup

Load the Google Maps JavaScript API before gmaps.js. Replace YOUR_API_KEY with your actual key:

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
<script src="gmaps.js"></script>

2. Basic Map Initialization

Create a container element and initialize the map:

<div id="map" style="width: 400px; height: 400px;"></div>

<script>
  var map = new GMaps({
    el: '#map',
    lat: -12.043333,
    lng: -77.028333,
    zoom: 15,
    mapType: 'roadmap'
  });
</script>

3. AMD/Require.js Configuration

Create a loader for Google Maps API (googlemapsapi.js):

define(['async!https://maps.googleapis.com/maps/api/js?v=3&key=YOUR_API_KEY'], function() {});

Configure Require.js:

require.config({
  paths: {
    "googlemapsapi": "path/to/googlemapsapi",
    "gmaps": "path/to/gmaps"
  },
  shim: {
    gmaps: {
      deps: ["googlemapsapi"],
      exports: "GMaps"
    }
  }
});

Build & Run

Development Build

# Install dependencies (first time only)
npm install

# Build distribution files
grunt

This generates gmaps.min.js from the modular source files in /lib/.

Local Development Server

Since this is a client-side library, use any static file server:

# Python 3
python -m http.server 8000

# Node.js (npx serve)
npx serve .

# PHP
php -S localhost:8000

Open http://localhost:8000 and navigate to the examples directory.

Deployment

Production Usage (CDN)

Include the minified library via CDN in your HTML:

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
<script src="https://cdn.jsdelivr.net/gh/hpneo/gmaps@0.4.25/gmaps.min.js"></script>

Bundler Integration (Webpack/Rollup)

Import as a module (ensure Google Maps API is loaded globally or via a loader):

import GMaps from 'gmaps';

const map = new GMaps({
  el: '#map',
  lat: -12.043333,
  lng: -77.028333
});

Static Maps Generation

For server-side rendering or email embedding, use the static map URL generator:

var staticMapURL = GMaps.staticMapURL({
  size: [640, 480],
  lat: -12.043333,
  lng: -77.028333,
  markers: [{lat: -12.043333, lng: -77.028333}]
});
// Returns: https://maps.googleapis.com/maps/api/staticmap?...

Module-Specific Features

Load specific features by including the relevant source files from /lib/:

• gmaps.core.js — Core functionality (required)
• gmaps.routes.js — Directions and routing
• gmaps.static.js — Static map generation
• gmaps.markers.js — Advanced marker management

Troubleshooting

"Google Maps API is required" Console Error

Cause: The Google Maps JavaScript library hasn't loaded before initializing GMaps.
Solution:

• Verify the Google Maps script tag appears before gmaps.js
• Check that your API key is valid and the Maps JavaScript API is enabled in Google Cloud Console
• Ensure you're using https:// in production (the library auto-detects protocol, but Google requires HTTPS for production)

Markers/Polylines Not Appearing

Cause: LatLng coordinate format mismatch.
Solution: Pass coordinates as [lat, lng] arrays or Google Maps LatLng objects. For GeoJSON format, set useGeoJSON: true in relevant methods.

AMD Loading Failures

Cause: Google Maps not loaded before GMaps instantiation.
Solution: Use the async! plugin with Require.js or the googlemaps-amd plugin to ensure proper loading order.

Context Menu Position Bugs

Cause: Scroll position not calculated correctly.
Solution: Ensure your map container has a defined position (relative/absolute) in CSS. Upgrade to v0.4.25+ for improved findAbsolutePosition calculations.

RemoveMarkers Performance Issues

Cause: Removing large marker clusters synchronously.
Solution: Upgrade to v0.4.23+ which includes optimizations for bulk marker removal.

SSL/HTTPS Mixed Content Warnings

Cause: Hardcoded http:// protocol in Google Maps URL.
Solution: Use protocol-relative URLs (//maps.google.com/...) or explicit https://. This is fixed in v0.4.17+.

Route Calculation Failures

Cause: Invalid origin/destination format or missing callback.
Solution:

• Use [lat, lng] arrays or address strings for origins/destinations
• Always provide an error callback in getRoutes() to handle denied requests or zero results
• Verify the Directions API is enabled in your Google Cloud project