Creé un plugin que simplifica la integración de Google Maps en Vite y React

Si estás usando Vite y React, probablemente hayas lidiado con la carga manual del API de Google Maps JavaScript API, el wrapping con providers, configuración repetida y boilerplate dentro de tu aplicación. Ahí es donde entra vite-plugin-google-maps: un plugin pensado para simplificar y acelerar la integración de Google Maps en apps React basadas en Vite.

¿Qué ofrece vite-plugin-google-maps?

Auto-configuración y cero boilerplate: el plugin autoenvuelve tu app con el provider necesario (APIProvider) no tenés que hacerlo manualmente.

Componente Map preconfigurado: expone un módulo virtual @google-maps/map que provee un componente Map listo para usar, con props por defecto que podés sobrescribir cuando lo necesites.

Defaults globales configurables: desde el zoom inicial, centro, controles (fullscreen, zoom control, etc.), hasta cómo responden los gestos en el mapa.

Soporte para librerías de Google Maps (places, marker, etc.): podés definir qué "libraries" cargar junto con el plugin.

Panel de desarrollo (debug): si activás debug: true, podés ver información útil, como estado de carga de mapa, nivel de zoom, posición del cursor, coordenadas de click útil para debugging y desarrollo.

Flexibilidad: porque podés utilizar las props del componente Map para sobreescribir defaults en ciertos mapas, lo que es ideal si tu app usa múltiples mapas con diferentes configuraciones.

Cómo ponerlo en marcha

Instalar el plugin:

pnpm install vite-plugin-google-maps
# o npm/yarn equivalente

Configurarlo en vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { GoogleMapsPlugin } from 'vite-plugin-google-maps';

export default defineConfig({
  plugins: [
    react(),
    GoogleMapsPlugin({
      apiKey: 'TU_GOOGLE_MAPS_API_KEY',
      libraries: ['places', 'marker'],       // por ejemplo
      debug: true,                           // opcional
      mapDefaults: {
        mapId: 'TU_MAP_ID',
        gestureHandling: 'greedy',
        defaultCenter: { lat: 40.7128, lng: -74.0060 },
        defaultZoom: 12,
        fullscreenControl: true,
        disableDefaultUI: false,
        // y otros controles como zoomControl, streetViewControl, etc.
      },
    }),
  ],
});

Usar el componente Map en tu app React:

import { Map } from '@google-maps/map';
import { AdvancedMarker } from '@vis.gl/react-google-maps';

function App() {
  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <Map>
        <AdvancedMarker position={{ lat: 40.7128, lng: -74.0060 }} />
      </Map>
    </div>
  );
}

export default App;

Si querés, podés sobrescribir props en Map para modificar configuración global (zoom, centro, controles, etc.) sólo para ese mapa.

Setup con TypeScript

Como @google-maps/map es un módulo virtual generado por el plugin, TypeScript no lo conoce por defecto. Para tener tipado completo y autocompletado en las props del componente Map, necesitás declarar el módulo en un archivo de tipos. Creá un types.d.ts (o agregalo a tu vite-env.d.ts) con lo siguiente:

// types.d.ts o vite-env.d.ts
declare module "@google-maps/map" {
  import React from "react";
  import { Map as GoogleMapBase } from "@vis.gl/react-google-maps";

  export const Map: React.FC<React.ComponentProps<typeof GoogleMapBase>>;
}

Con esto, el componente Map va a tener las mismas props tipadas que el Map original de @vis.gl/react-google-maps, sin errores de TypeScript.

¿Por qué desarrollé este plugin?

Integrar Google Maps en un proyecto React + Vite suele implicar bastante boilerplate: provider, configuración, librerías, carga condicional; me pareció que había lugar para una abstracción que lo simplifique.

Quería entregar una experiencia de integración fluida, sin repetición de configuración cada vez que uso un mapa, especialmente en proyectos con múltiples mapas.

Quiero que la configuración por defecto sea sana, pero fácilmente sobreescribible: muchas apps sólo necesitan un mapa básico, otras necesitan distintos mapas el plugin sirve para ambos casos.

¿Para quién es ideal?

Proyectos nuevos usando Vite + React que necesiten mapas: permite empezar con Google Maps en unos minutos sin complicaciones.

Apps con múltiples mapas o diferentes configuraciones de mapas: podes establecer defaults globales y sobreescribir cuando sea necesario.

Equipos que buscan evitar boilerplate repetido, simplificando onboarding de nuevos desarrolladores.

Cosas a tener en cuenta / Limitaciones

Necesitás una API Key de Google Maps como cualquier integración del API oficial. El plugin no gestiona la generación de la API key por vos. Esto es parte del flujo estándar de la Google Cloud Platform.

El plugin depende de la librería @vis.gl/react-google-maps si tu stack cambia, podría requerir ajustes.

Es experimental: aunque ya funcional, puede haber edge-cases o situaciones particulares donde convenga revisar configuración manual.

Conclusión

vite-plugin-google-maps nació para devolvernos tiempo y simplicidad: en lugar de repetir configuración y wrappers cada vez que queremos un mapa, basta con instalar el plugin, configurarlo una vez y usar el componente Map directamente. Si usás Vite + React y necesitás Google Maps, puede ayudarte a arrancar rápido, mantener tu código limpio y enfocarte en lo importante.

Si te interesa y para vos que ya sos desarrollador web me encantaría saber tu feedback, ideas de mejoras o casos de uso donde se vuelva indispensable.

Relacionado

• vite-plugin-google-maps
• @vis.gl/react-google-maps