I created a plugin that simplifies the integration of Google Maps into Vite and React

If you're using Vite and React, you've probably dealt with manually loading the Google Maps JavaScript API, wrapping your app with providers, repeated configuration and boilerplate all over your codebase. That's where vite-plugin-google-maps comes in: a plugin designed to simplify and speed up Google Maps integration in Vite-based React apps.

What does vite-plugin-google-maps offer?

Auto-configuration and zero boilerplate: the plugin automatically wraps your app with the necessary provider (APIProvider) — you don't have to do it manually.

Pre-configured Map component: exposes a virtual module @google-maps/map that provides a Map component ready to use, with default props you can override whenever you need.

Globally configurable defaults: from the initial zoom and center, to controls (fullscreen, zoom control, etc.), to how gestures behave on the map.

Google Maps libraries support (places, marker, etc.): you can define which libraries to load alongside the plugin.

Development panel (debug): if you enable debug: true, you can see useful information like map load status, zoom level, cursor position, and click coordinates — handy for debugging and development.

Flexibility: you can use the Map component's props to override defaults for specific maps, which is ideal if your app uses multiple maps with different configurations.

How to get started

Install the plugin:

pnpm install vite-plugin-google-maps
# or npm/yarn equivalent

Configure it in 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: 'YOUR_GOOGLE_MAPS_API_KEY',
      libraries: ['places', 'marker'],       // for example
      debug: true,                           // optional
      mapDefaults: {
        mapId: 'YOUR_MAP_ID',
        gestureHandling: 'greedy',
        defaultCenter: { lat: 40.7128, lng: -74.0060 },
        defaultZoom: 12,
        fullscreenControl: true,
        disableDefaultUI: false,
        // other controls like zoomControl, streetViewControl, etc.
      },
    }),
  ],
});

Use the Map component in your React app:

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;

You can override props on Map to change the global configuration (zoom, center, controls, etc.) for that specific map only.

TypeScript Setup

Since @google-maps/map is a virtual module generated by the plugin, TypeScript doesn't know about it by default. To get full typing and autocomplete for the Map component's props, you need to declare the module in a type declaration file. Create a types.d.ts (or add it to your vite-env.d.ts) with the following:

// types.d.ts or 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>>;
}

With this, the Map component will have the same typed props as the original Map from @vis.gl/react-google-maps, with no TypeScript errors.

Why I built this plugin

Integrating Google Maps into a React + Vite project usually involves a lot of boilerplate: provider setup, configuration, libraries, conditional loading — I felt there was room for an abstraction that simplifies all of that.

I wanted to deliver a smooth integration experience, without repeating configuration every time I use a map, especially in projects with multiple maps.

I wanted the default configuration to be sane but easily overridable: many apps just need a basic map, others need different maps — the plugin works for both cases.

Who is it ideal for?

New projects using Vite + React that need maps: lets you get started with Google Maps in minutes without any hassle.

Apps with multiple maps or different map configurations: you can set global defaults and override them when needed.

Teams looking to avoid repeated boilerplate, simplifying onboarding for new developers.

Things to keep in mind / Limitations

You need a Google Maps API Key like any integration with the official API. The plugin doesn't handle key generation for you — that's part of the standard Google Cloud Platform flow.

The plugin depends on @vis.gl/react-google-maps — if your stack changes, some adjustments may be needed.

It's experimental: while functional, there may be edge cases or specific situations where manual configuration makes more sense.

Conclusion

vite-plugin-google-maps was built to give back time and simplicity: instead of repeating configuration and wrappers every time you need a map, just install the plugin, configure it once, and use the Map component directly. If you're using Vite + React and need Google Maps, it can help you get started quickly, keep your code clean, and focus on what matters.

If you're a web developer and this interests you, I'd love to hear your feedback, improvement ideas, or use cases where it becomes indispensable.

Related

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