fix(google-maps): static maps proxy, color mode, and bug fixes

- Add googleStaticMapsProxy config for CORS fixes and caching (#380, #83)
  - API key stored server-side only (not exposed to client)
  - Referer validation to prevent external abuse
- Add mapIds prop for light/dark color mode support (#539)
- Fix MarkerClusterer optional peer dep with inline types (#540)
- Add PinElement cleanup on unmount
- Fix importLibrary cache to retry on failure

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: harlan-zw

src/module.ts

@@ -3,6 +3,7 @@ import {
   addComponentsDir,
   addImports,
   addPluginTemplate,
+  addServerHandler,
   addTemplate,
   createResolver,
   defineNuxtModule,
@@ -78,6 +79,22 @@ export interface ModuleOptions {
      */
     integrity?: boolean | 'sha256' | 'sha384' | 'sha512'
   }
+  /**
+   * Google Static Maps proxy configuration.
+   * Proxies static map images through your server to fix CORS issues and enable caching.
+   */
+  googleStaticMapsProxy?: {
+    /**
+     * Enable proxying Google Static Maps through your own origin.
+     * @default false
+     */
+    enabled?: boolean
+    /**
+     * Cache duration for static map images in seconds.
+     * @default 3600 (1 hour)
+     */
+    cacheMaxAge?: number
+  }
   /**
    * Whether the module is enabled.
    *
@@ -115,6 +132,10 @@ export default defineNuxtModule<ModuleOptions>({
         timeout: 15_000, // Configures the maximum time (in milliseconds) allowed for each fetch attempt.
       },
     },
+    googleStaticMapsProxy: {
+      enabled: false,
+      cacheMaxAge: 3600,
+    },
     enabled: true,
     debug: false,
   },
@@ -136,11 +157,21 @@ export default defineNuxtModule<ModuleOptions>({
     if (unheadVersion?.startsWith('1')) {
       logger.error(`Nuxt Scripts requires Unhead >= 2, you are using v${unheadVersion}. Please run \`nuxi upgrade --clean\` to upgrade...`)
     }
-    nuxt.options.runtimeConfig['nuxt-scripts'] = { version }
+    nuxt.options.runtimeConfig['nuxt-scripts'] = {
+      version,
+      // Private proxy config with API key (server-side only)
+      googleStaticMapsProxy: config.googleStaticMapsProxy?.enabled
+        ? { apiKey: (nuxt.options.runtimeConfig.public.scripts as any)?.googleMaps?.apiKey }
+        : undefined,
+    }
     nuxt.options.runtimeConfig.public['nuxt-scripts'] = {
       // expose for devtools
       version: nuxt.options.dev ? version : undefined,
       defaultScriptOptions: config.defaultScriptOptions,
+      // Only expose enabled and cacheMaxAge to client, not apiKey
+      googleStaticMapsProxy: config.googleStaticMapsProxy?.enabled
+        ? { enabled: true, cacheMaxAge: config.googleStaticMapsProxy.cacheMaxAge }
+        : undefined,
     }
 
     // Merge registry config with existing runtimeConfig.public.scripts for proper env var resolution
@@ -250,6 +281,14 @@ export default defineNuxtModule<ModuleOptions>({
       })
     })
 
+    // Add Google Static Maps proxy handler if enabled
+    if (config.googleStaticMapsProxy?.enabled) {
+      addServerHandler({
+        route: '/_scripts/google-static-maps-proxy',
+        handler: await resolvePath('./runtime/server/google-static-maps-proxy'),
+      })
+    }
+
     if (nuxt.options.dev)
       setupDevToolsUI(config, resolvePath)
   },

src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue

@@ -6,7 +6,7 @@ import { withQuery } from 'ufo'
 import type { QueryObject } from 'ufo'
 import { defu } from 'defu'
 import { hash } from 'ohash'
-import { useHead } from 'nuxt/app'
+import { tryUseNuxtApp, useHead, useRuntimeConfig } from 'nuxt/app'
 import type { ElementScriptTrigger } from '#nuxt-scripts/types'
 import { scriptRuntimeConfig } from '#nuxt-scripts/utils'
 import { useScriptTriggerElement } from '#nuxt-scripts/composables/useScriptTriggerElement'
@@ -104,6 +104,17 @@ const props = withDefaults(defineProps<{
    * Extra Markers to add to the map.
    */
   markers?: (`${string},${string}` | google.maps.marker.AdvancedMarkerElementOptions)[]
+  /**
+   * Map IDs for light and dark color modes.
+   * When provided, the map will automatically switch styles based on color mode.
+   * Requires @nuxtjs/color-mode or manual colorMode prop.
+   */
+  mapIds?: { light?: string, dark?: string }
+  /**
+   * Manual color mode control. When provided, overrides auto-detection from @nuxtjs/color-mode.
+   * Accepts 'light', 'dark', or a reactive ref.
+   */
+  colorMode?: 'light' | 'dark'
 }>(), {
   // @ts-expect-error untyped
   trigger: ['mouseenter', 'mouseover', 'mousedown'],
@@ -119,6 +130,26 @@ const emits = defineEmits<{
 }>()
 
 const apiKey = props.apiKey || scriptRuntimeConfig('googleMaps')?.apiKey
+const runtimeConfig = useRuntimeConfig()
+const proxyConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleStaticMapsProxy
+
+// Color mode support - try to auto-detect from @nuxtjs/color-mode
+const nuxtApp = tryUseNuxtApp()
+const nuxtColorMode = nuxtApp?.$colorMode as { value: string } | undefined
+
+const currentColorMode = computed(() => {
+  if (props.colorMode)
+    return props.colorMode
+  if (nuxtColorMode?.value)
+    return nuxtColorMode.value === 'dark' ? 'dark' : 'light'
+  return 'light'
+})
+
+const currentMapId = computed(() => {
+  if (!props.mapIds)
+    return props.mapOptions?.mapId
+  return props.mapIds[currentColorMode.value] || props.mapIds.light || props.mapOptions?.mapId
+})
 
 const mapsApi = ref<typeof google.maps | undefined>()
 
@@ -144,10 +175,10 @@ const { load, status, onLoaded } = useScriptGoogleMaps({
 })
 
 const options = computed(() => {
-  return defu({ center: centerOverride.value }, props.mapOptions, {
+  const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'map')
+  return defu({ center: centerOverride.value, mapId }, props.mapOptions, {
     center: props.center,
     zoom: 15,
-    mapId: props.mapOptions?.styles ? undefined : 'map',
   })
 })
 const ready = ref(false)
@@ -266,8 +297,13 @@ function importLibrary<T>(key: string): Promise<T> {
       }
     }, { immediate: true })
   })
-  libraries.set(key, p)
-  return p as any as Promise<T>
+  // Clear cache on failure to allow retry
+  const cached = Promise.resolve(p).catch((err) => {
+    libraries.delete(key)
+    throw err
+  })
+  libraries.set(key, cached)
+  return cached as Promise<T>
 }
 
 const googleMaps = {
@@ -380,7 +416,7 @@ onMounted(() => {
   })
 })
 
-if (import.meta.server) {
+if (import.meta.server && !proxyConfig?.enabled) {
   useHead({
     link: [
       {
@@ -419,7 +455,8 @@ const placeholder = computed(() => {
     center,
   }, {
     size: `${props.width}x${props.height}`,
-    key: apiKey,
+    // Only include API key if not using proxy (proxy injects it server-side)
+    key: proxyConfig?.enabled ? undefined : apiKey,
     scale: 2, // we assume a high DPI to avoid hydration issues
     style: props.mapOptions?.styles ? transformMapStyles(props.mapOptions.styles) : undefined,
     markers: [
@@ -438,7 +475,12 @@ const placeholder = computed(() => {
       })
       .join('|'),
   })
-  return withQuery('https://maps.googleapis.com/maps/api/staticmap', placeholderOptions as QueryObject)
+
+  const baseUrl = proxyConfig?.enabled
+    ? '/_scripts/google-static-maps-proxy'
+    : 'https://maps.googleapis.com/maps/api/staticmap'
+
+  return withQuery(baseUrl, placeholderOptions as QueryObject)
 })
 
 const placeholderAttrs = computed(() => {

src/runtime/components/GoogleMaps/ScriptGoogleMapsMarkerClusterer.vue

@@ -3,13 +3,28 @@
 </template>
 
 <script lang="ts">
-import type { MarkerClusterer, MarkerClustererOptions } from '@googlemaps/markerclusterer'
 import { inject, onUnmounted, provide, shallowRef, type InjectionKey, type ShallowRef } from 'vue'
 import { whenever } from '@vueuse/core'
 import { MAP_INJECTION_KEY } from './ScriptGoogleMaps.vue'
 
+// Inline types to avoid requiring @googlemaps/markerclusterer as a build-time dependency
+export interface MarkerClustererInstance {
+  render: () => void
+  setMap: (map: google.maps.Map | null) => void
+  addListener: (event: string, handler: () => void) => void
+  addMarker: (marker: google.maps.marker.AdvancedMarkerElement | google.maps.Marker, noDraw?: boolean) => void
+  removeMarker: (marker: google.maps.marker.AdvancedMarkerElement | google.maps.Marker, noDraw?: boolean) => boolean
+}
+
+export interface MarkerClustererOptions {
+  markers?: google.maps.marker.AdvancedMarkerElement[]
+  algorithm?: unknown
+  renderer?: unknown
+  onClusterClick?: unknown
+}
+
 export const MARKER_CLUSTERER_INJECTION_KEY = Symbol('marker-clusterer') as InjectionKey<{
-  markerClusterer: ShallowRef<MarkerClusterer | undefined>
+  markerClusterer: ShallowRef<MarkerClustererInstance | undefined>
   requestRerender: () => void
 }>
 </script>
@@ -26,19 +41,19 @@ const markerClustererEvents = [
 ] as const
 
 const emit = defineEmits<{
-  (event: typeof markerClustererEvents[number], payload: MarkerClusterer): void
+  (event: typeof markerClustererEvents[number], payload: MarkerClustererInstance): void
 }>()
 
 const mapContext = inject(MAP_INJECTION_KEY, undefined)
 
-const markerClusterer = shallowRef<MarkerClusterer | undefined>(undefined)
+const markerClusterer = shallowRef<MarkerClustererInstance | undefined>(undefined)
 
 whenever(() => mapContext?.map.value, async (map) => {
   const { MarkerClusterer } = await import('@googlemaps/markerclusterer')
   markerClusterer.value = new MarkerClusterer({
     map,
     ...props.options,
-  })
+  } as any) as MarkerClustererInstance
 
   setupMarkerClustererEventListeners(markerClusterer.value)
 }, {
@@ -76,9 +91,9 @@ provide(
   },
 )
 
-function setupMarkerClustererEventListeners(markerClusterer: MarkerClusterer) {
+function setupMarkerClustererEventListeners(clusterer: MarkerClustererInstance) {
   markerClustererEvents.forEach((event) => {
-    markerClusterer.addListener(event, () => emit(event, markerClusterer))
+    clusterer.addListener(event, () => emit(event, clusterer))
   })
 }
 </script>

src/runtime/components/GoogleMaps/ScriptGoogleMapsPinElement.vue

@@ -2,7 +2,7 @@
 </template>
 
 <script setup lang="ts">
-import { inject, shallowRef } from 'vue'
+import { inject, onUnmounted, shallowRef } from 'vue'
 import { whenever } from '@vueuse/core'
 import { MAP_INJECTION_KEY } from './ScriptGoogleMaps.vue'
 import { ADVANCED_MARKER_ELEMENT_INJECTION_KEY } from './ScriptGoogleMapsAdvancedMarkerElement.vue'
@@ -42,4 +42,12 @@ whenever(
     once: true,
   },
 )
+
+onUnmounted(() => {
+  if (advancedMarkerElementContext?.advancedMarkerElement.value && pinElement.value) {
+    // Clear the content from the parent marker
+    advancedMarkerElementContext.advancedMarkerElement.value.content = null
+  }
+  pinElement.value = undefined
+})
 </script>

src/runtime/server/google-static-maps-proxy.ts

@@ -0,0 +1,67 @@
+import { createError, defineEventHandler, getHeader, getQuery, setHeader } from 'h3'
+import { $fetch } from 'ofetch'
+import { withQuery } from 'ufo'
+import { useRuntimeConfig } from '#imports'
+
+export default defineEventHandler(async (event) => {
+  const runtimeConfig = useRuntimeConfig()
+  const publicConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleStaticMapsProxy
+  const privateConfig = (runtimeConfig['nuxt-scripts'] as any)?.googleStaticMapsProxy
+
+  if (!publicConfig?.enabled) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Google Static Maps proxy is not enabled',
+    })
+  }
+
+  // Get API key from private config (server-side only, not exposed to client)
+  const apiKey = privateConfig?.apiKey
+  if (!apiKey) {
+    throw createError({
+      statusCode: 500,
+      statusMessage: 'Google Maps API key not configured for proxy',
+    })
+  }
+
+  // Validate referer to prevent external abuse
+  const referer = getHeader(event, 'referer')
+  const host = getHeader(event, 'host')
+  if (referer && host) {
+    const refererUrl = new URL(referer).host
+    if (refererUrl !== host) {
+      throw createError({
+        statusCode: 403,
+        statusMessage: 'Invalid referer',
+      })
+    }
+  }
+
+  const query = getQuery(event)
+
+  // Remove any client-provided key and use server-side key
+  const { key: _clientKey, ...safeQuery } = query
+
+  const googleMapsUrl = withQuery('https://maps.googleapis.com/maps/api/staticmap', {
+    ...safeQuery,
+    key: apiKey,
+  })
+
+  const response = await $fetch.raw(googleMapsUrl, {
+    headers: {
+      'User-Agent': 'Nuxt Scripts Google Static Maps Proxy',
+    },
+  }).catch((error: any) => {
+    throw createError({
+      statusCode: error.statusCode || 500,
+      statusMessage: error.statusMessage || 'Failed to fetch static map',
+    })
+  })
+
+  const cacheMaxAge = publicConfig.cacheMaxAge || 3600
+  setHeader(event, 'Content-Type', response.headers.get('content-type') || 'image/png')
+  setHeader(event, 'Cache-Control', `public, max-age=${cacheMaxAge}, s-maxage=${cacheMaxAge}`)
+  setHeader(event, 'Vary', 'Accept-Encoding')
+
+  return response._data
+})