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

[harlan-zw]

🔗 Linked issue

Resolves #380, #83, #539, #540
Supersedes #516

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Google Maps had several pain points: CORS issues with static map placeholders when using crossOriginEmbedderPolicy, no way to switch map styles based on color mode, and MarkerClusterer types breaking builds when the package wasn't installed.

Added a server-side static maps proxy that serves images from same origin (fixing CORS) with caching to reduce API costs. The proxy keeps the API key server-side only and validates referer headers to prevent abuse. Added mapIds prop to switch between light/dark Map IDs reactively when color mode changes. Replaced top-level type imports with inline types so MarkerClusterer is truly optional. Also fixed PinElement memory leak and importLibrary cache not retrying on failure.

// Static maps proxy - API key stays server-side
scripts: {
  googleStaticMapsProxy: { enabled: true, cacheMaxAge: 3600 }
}

<!-- Color mode support -->
<ScriptGoogleMaps :map-ids="{ light: 'LIGHT_ID', dark: 'DARK_ID' }" />

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
scripts-docs	Ready	Preview, Comment	Jan 18, 2026 4:00am
scripts-playground	Ready	Preview, Comment	Jan 18, 2026 4:00am

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nuxt/scripts/@nuxt/scripts@587

commit: b8cac43

[vercel]

Suggested change

	const refererUrl = new URL(referer).host
	if (refererUrl !== host) {
	throw createError({
	statusCode: 403,
	statusMessage: 'Invalid referer',
	try {
	const refererUrl = new URL(referer).host
	if (refererUrl !== host) {
	throw createError({
	statusCode: 403,
	statusMessage: 'Invalid referer',
	})
	}
	} catch (error) {
	// Re-throw Nuxt errors as-is
	if (error && typeof error === 'object' && 'statusCode' in error) {
	throw error
	}
	// Handle URL parsing errors
	throw createError({
	statusCode: 400,
	statusMessage: 'Invalid referer URL',

The referer header URL parsing can throw an uncaught error if the referer is malformed, causing an unhandled exception instead of a proper HTTP error response.

View Details

Analysis

Unhandled URL parsing error in Google Static Maps proxy referer validation

What fails: The google-static-maps-proxy.ts event handler crashes with an unhandled TypeError when the referer header contains a malformed URL.

How to reproduce:

# Send a request with a malformed referer header
curl -H "Referer: this-is-not-a-valid-url" http://localhost:3000/api/google-static-maps

Result: Returns 500 Internal Server Error due to unhandled exception from new URL() constructor throwing TypeError: Invalid URL

Expected: Should return 400 Bad Request with proper error message, consistent with other validation errors in the function that use createError() for HTTP error responses

Details: The referer header can contain any string value from the HTTP request. When new URL(referer) is called without try-catch wrapping (line 31), it throws a TypeError for malformed URLs. According to JavaScript best practices, the new URL() constructor should be wrapped in error handling when parsing untrusted input.