GmapVue

Google Maps components and composables for Vue 3. The Vue 2 package is frozen and kept only for existing applications.

Overview

GmapVue is a pnpm monorepo that provides Vue wrappers for the Google Maps JavaScript API.

• Vue 3 package: @gmap-vue/v3, the actively developed package.
• Vue 2 package: gmap-vue, frozen and no longer actively maintained. Existing Vue 2 apps can keep using it, but migration to Vue 3 is recommended.
• Documentation: Docusaurus site published at https://diegoazh.github.io/gmap-vue/.

The project is a maintained fork of vue2-google-maps, updated to support modern Vue, typed package entrypoints, and component-level access to Google Maps instances.

Documentation

Start with the published docs:

• Vue 3 documentation
• Vue 2 legacy documentation
• Component API reference

Packages

Package	Location	Status	Purpose
@gmap-vue/v3	packages/v3	Active	Vue 3 plugin, components, composables, keys, interfaces, and types.
gmap-vue	packages/v2	Frozen legacy	Vue 2 plugin kept for existing applications. No active maintenance; migrate to @gmap-vue/v3 when possible.
docs	packages/documentation	Active	Docusaurus documentation site.

Install

pnpm add @gmap-vue/v3

Peer/runtime dependencies are resolved by your app, including Vue and the Google Maps JavaScript API types used by your tooling.

Vue 3 quick start

import { createApp } from 'vue';
import { createGmapVuePlugin } from '@gmap-vue/v3';
import '@gmap-vue/v3/dist/style.css';
import App from './App.vue';

createApp(App)
  .use(
    createGmapVuePlugin({
      load: {
        key: import.meta.env.VITE_GOOGLE_MAPS_API_KEY,
      },
    }),
  )
  .mount('#app');

<template>
  <GmvMap
    :center="{ lat: -34.6037, lng: -58.3816 }"
    :zoom="12"
    style="width: 100%; height: 500px"
  />
</template>

For production apps, restrict browser API keys in Google Cloud Console by HTTP referrer and by required APIs.

Development

This repository uses pnpm workspaces.

pnpm install

Common root commands:

pnpm run serve:docs   # Start the Docusaurus site
pnpm run build:all    # Build workspace packages
pnpm run test         # Run package test:ci scripts
pnpm run test:e2e     # Run package e2e CI scripts
pnpm run lint         # Run workspace lint scripts

Package-specific examples:

pnpm run --filter @gmap-vue/v3 build
pnpm run --filter @gmap-vue/v3 test:ci
pnpm run --filter @gmap-vue/v3 type-check
pnpm run --filter docs build
pnpm run --filter docs typecheck

Validation before opening a PR

Run the checks that match your change. For broad changes, use the full root validation path:

pnpm run lint
pnpm run test
pnpm run test:e2e

E2E tests require packages/v3/cypress/runner/.env with VITE_GOOGLE_API_KEY. If Google Cloud billing or API key restrictions are not correctly configured, e2e tests can fail with Google Maps runtime errors.

Contributing

Contributions are welcome. Before opening a PR:

1. Read AGENTS.md and .github/copilot-instructions.md.
2. Keep changes scoped and reviewable.
3. Use conventional commits with a required scope, for example docs(docs): improve vue 3 guide.
4. Include validation evidence in the PR description.

License

MIT. See package-level license files where applicable.