@nuxt/scripts 1.0.0-rc.5 → 1.0.0-rc.7

package/dist/module.mjs

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, appendFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { useNuxt, addDevServerHandler, extendRouteRules, tryUseNuxt, createResolver, extendViteConfig, logger as logger$1, useLogger, addTypeTemplate, defineNuxtModule, addPluginTemplate, addServerHandler, addImports, addComponentsDir, addTemplate, hasNuxtModule, addBuildPlugin } from '@nuxt/kit';
 import { defu } from 'defu';
 import { join, resolve } from 'pathe';
@@ -12,7 +13,6 @@ import { isCI, provider } from 'std-env';
 import { parseAndWalk, ScopeTracker, walk, ScopeTrackerFunction, ScopeTrackerIdentifier, ScopeTrackerFunctionParam, ScopeTrackerVariable } from 'oxc-walker';
 import { createUnplugin } from 'unplugin';
 import { pathToFileURL } from 'node:url';
-import { createHash } from 'node:crypto';
 import fsp from 'node:fs/promises';
 import { colors } from 'consola/utils';
 import MagicString from 'magic-string';
@@ -1373,6 +1373,42 @@ function fixSelfClosingScriptComponents(nuxt) {
 }
 const UPPER_RE = /([A-Z])/g;
 const toScreamingSnake = (s) => s.replace(UPPER_RE, "_$1").toUpperCase();
+const PROXY_SECRET_ENV_KEY = "NUXT_SCRIPTS_PROXY_SECRET";
+const PROXY_SECRET_ENV_LINE_RE = /^NUXT_SCRIPTS_PROXY_SECRET=/m;
+const PROXY_SECRET_ENV_VALUE_RE = /^NUXT_SCRIPTS_PROXY_SECRET=(.+)$/m;
+function resolveProxySecret(rootDir, isDev, configSecret, autoGenerate = true) {
+  if (configSecret)
+    return { secret: configSecret, ephemeral: false, source: "config" };
+  const envSecret = process.env[PROXY_SECRET_ENV_KEY];
+  if (envSecret)
+    return { secret: envSecret, ephemeral: false, source: "env" };
+  if (!isDev || !autoGenerate)
+    return void 0;
+  const secret = randomBytes(32).toString("hex");
+  const envPath = resolve(rootDir, ".env");
+  const line = `${PROXY_SECRET_ENV_KEY}=${secret}
+`;
+  try {
+    if (existsSync(envPath)) {
+      const contents = readFileSync(envPath, "utf-8");
+      if (PROXY_SECRET_ENV_LINE_RE.test(contents)) {
+        const match = contents.match(PROXY_SECRET_ENV_VALUE_RE);
+        if (match?.[1])
+          return { secret: match[1].trim(), ephemeral: false, source: "dotenv-generated" };
+      }
+      appendFileSync(envPath, contents.endsWith("\n") ? line : `
+${line}`);
+    } else {
+      writeFileSync(envPath, `# Generated by @nuxt/scripts
+${line}`);
+    }
+    process.env[PROXY_SECRET_ENV_KEY] = secret;
+    return { secret, ephemeral: false, source: "dotenv-generated" };
+  } catch {
+    process.env[PROXY_SECRET_ENV_KEY] = secret;
+    return { secret, ephemeral: true, source: "memory-generated" };
+  }
+}
 function isProxyDisabled(registryKey, registry2, runtimeConfig) {
   const entry = registry2?.[registryKey];
   if (!entry)
@@ -1684,12 +1720,12 @@ They will load directly from third-party servers.`
         if (totalDomains > 0 && nuxt.options.dev) {
           logger.success(`Proxy mode enabled for ${registryKeys.length} script(s), ${totalDomains} domain(s) proxied (privacy: ${privacyLabel})`);
         }
-        const staticPresets = ["static", "github-pages", "cloudflare-pages-static", "netlify-static", "azure-static", "firebase-static"];
-        const preset = process.env.NITRO_PRESET || "";
-        if (staticPresets.includes(preset)) {
+        const proxyStaticPresets = ["static", "github-pages", "cloudflare-pages-static", "netlify-static", "azure-static", "firebase-static"];
+        const proxyPreset = process.env.NITRO_PRESET || "";
+        if (proxyStaticPresets.includes(proxyPreset)) {
           logger.warn(
-            `Proxy collection endpoints require a server runtime (detected: ${preset || "static"}).
-Scripts will be bundled, but collection requests will not be proxied.
+            `Proxy collection endpoints require a server runtime (detected: ${proxyPreset || "static"}).
+Scripts will be bundled, but collection requests will not be proxied and URL signing will be unavailable.
 Options: configure platform rewrites, switch to server-rendered mode, or disable with proxy: false.`
           );
         }
@@ -1736,6 +1772,7 @@ Options: configure platform rewrites, switch to server-rendered mode, or disable
     });
     const scriptsPrefix = config.prefix || "/_scripts";
     const enabledEndpoints = {};
+    let anyHandlerRequiresSigning = false;
     for (const script of scripts) {
       if (!script.serverHandlers?.length || !script.registryKey)
         continue;
@@ -1744,11 +1781,14 @@ Options: configure platform rewrites, switch to server-rendered mode, or disable
         continue;
       enabledEndpoints[script.registryKey] = true;
       for (const handler of script.serverHandlers) {
+        const resolvedRoute = handler.route.replace("/_scripts", scriptsPrefix);
         addServerHandler({
-          route: handler.route.replace("/_scripts", scriptsPrefix),
+          route: resolvedRoute,
           handler: handler.handler,
           middleware: handler.middleware
         });
+        if (handler.requiresSigning)
+          anyHandlerRequiresSigning = true;
       }
       if (script.registryKey === "gravatar") {
         const gravatarConfig = config.registry?.gravatar?.[0] || {};
@@ -1768,7 +1808,38 @@ Options: configure platform rewrites, switch to server-rendered mode, or disable
       { endpoints: enabledEndpoints },
       nuxt.options.runtimeConfig.public["nuxt-scripts"]
     );
+    const staticPresets = ["static", "github-pages", "cloudflare-pages-static", "netlify-static", "azure-static", "firebase-static"];
+    const nitroPreset = process.env.NITRO_PRESET || "";
+    const isStaticTarget = staticPresets.includes(nitroPreset);
+    const isSpa = nuxt.options.ssr === false;
+    if (anyHandlerRequiresSigning && (isSpa || isStaticTarget)) {
+      logger.warn(
+        `[security] URL signing requires a server runtime${isStaticTarget ? ` (detected preset: ${nitroPreset})` : " (ssr: false)"}.
+  Proxy endpoints will work without signature verification.
+  To enable signing, deploy with a server-rendered target or configure platform-level rewrites.`
+      );
+    } else if (anyHandlerRequiresSigning) {
+      const proxySecretResolved = resolveProxySecret(
+        nuxt.options.rootDir,
+        !!nuxt.options.dev,
+        config.security?.secret,
+        config.security?.autoGenerateSecret !== false
+      );
+      if (proxySecretResolved?.source === "dotenv-generated")
+        logger.info(`[security] Generated ${PROXY_SECRET_ENV_KEY} in .env for signed proxy URLs.`);
+      else if (proxySecretResolved?.source === "memory-generated")
+        logger.warn(`[security] Generated an in-memory ${PROXY_SECRET_ENV_KEY} (could not write .env). Signed URLs will break across restarts.`);
+      if (proxySecretResolved?.secret) {
+        nuxt.options.runtimeConfig["nuxt-scripts"].proxySecret = proxySecretResolved.secret;
+      } else if (!nuxt.options.dev) {
+        logger.warn(
+          `[security] ${PROXY_SECRET_ENV_KEY} is not set. Proxy endpoints will pass requests through without signature verification.
+  Generate one with: npx @nuxt/scripts generate-secret
+  Then set the env var: ${PROXY_SECRET_ENV_KEY}=<secret>`
+        );
+      }
+    }
   }
 });
 
-export { applyAutoInject, module$1 as default, isProxyDisabled };
+export { applyAutoInject, module$1 as default, isProxyDisabled, resolveProxySecret };

package/dist/registry.mjs

@@ -554,8 +554,8 @@ async function registry(resolve) {
       envDefaults: { apiKey: "" },
       category: "content",
       serverHandlers: [
-        { route: "/_scripts/proxy/google-static-maps", handler: "./runtime/server/google-static-maps-proxy" },
-        { route: "/_scripts/proxy/google-maps-geocode", handler: "./runtime/server/google-maps-geocode-proxy" }
+        { route: "/_scripts/proxy/google-static-maps", handler: "./runtime/server/google-static-maps-proxy", requiresSigning: true },
+        { route: "/_scripts/proxy/google-maps-geocode", handler: "./runtime/server/google-maps-geocode-proxy", requiresSigning: true }
       ]
     }),
     def("blueskyEmbed", {
@@ -564,8 +564,8 @@ async function registry(resolve) {
       label: "Bluesky Embed",
       category: "content",
       serverHandlers: [
-        { route: "/_scripts/embed/bluesky", handler: "./runtime/server/bluesky-embed" },
-        { route: "/_scripts/embed/bluesky-image", handler: "./runtime/server/bluesky-embed-image" }
+        { route: "/_scripts/embed/bluesky", handler: "./runtime/server/bluesky-embed", requiresSigning: true },
+        { route: "/_scripts/embed/bluesky-image", handler: "./runtime/server/bluesky-embed-image", requiresSigning: true }
       ]
     }),
     def("instagramEmbed", {
@@ -574,9 +574,9 @@ async function registry(resolve) {
       label: "Instagram Embed",
       category: "content",
       serverHandlers: [
-        { route: "/_scripts/embed/instagram", handler: "./runtime/server/instagram-embed" },
-        { route: "/_scripts/embed/instagram-image", handler: "./runtime/server/instagram-embed-image" },
-        { route: "/_scripts/embed/instagram-asset", handler: "./runtime/server/instagram-embed-asset" }
+        { route: "/_scripts/embed/instagram", handler: "./runtime/server/instagram-embed", requiresSigning: true },
+        { route: "/_scripts/embed/instagram-image", handler: "./runtime/server/instagram-embed-image", requiresSigning: true },
+        { route: "/_scripts/embed/instagram-asset", handler: "./runtime/server/instagram-embed-asset", requiresSigning: true }
       ]
     }),
     def("xEmbed", {
@@ -585,8 +585,8 @@ async function registry(resolve) {
       label: "X Embed",
       category: "content",
       serverHandlers: [
-        { route: "/_scripts/embed/x", handler: "./runtime/server/x-embed" },
-        { route: "/_scripts/embed/x-image", handler: "./runtime/server/x-embed-image" }
+        { route: "/_scripts/embed/x", handler: "./runtime/server/x-embed", requiresSigning: true },
+        { route: "/_scripts/embed/x-image", handler: "./runtime/server/x-embed-image", requiresSigning: true }
       ]
     }),
     // support
@@ -690,7 +690,7 @@ async function registry(resolve) {
         privacy: PRIVACY_IP_ONLY
       },
       serverHandlers: [
-        { route: "/_scripts/proxy/gravatar", handler: "./runtime/server/gravatar-proxy" }
+        { route: "/_scripts/proxy/gravatar", handler: "./runtime/server/gravatar-proxy", requiresSigning: true }
       ]
     })
   ]);

package/dist/runtime/components/GoogleMaps/ScriptGoogleMaps.d.vue.ts

@@ -1,11 +1,10 @@
 import type { ElementScriptTrigger } from '#nuxt-scripts/types';
 import type { HTMLAttributes, ReservedProps, ShallowRef } from 'vue';
 export { MAP_INJECTION_KEY } from './useGoogleMapsResource.js';
-declare const _default: typeof __VLS_export;
-export default _default;
-declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
+export interface ScriptGoogleMapsProps {
     /**
      * Defines the trigger event to load the script.
+     * @default ['mouseenter', 'mouseover', 'mousedown']
      */
     trigger?: ElementScriptTrigger;
     /**
@@ -14,11 +13,20 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     apiKey?: string;
     /**
      * A latitude / longitude of where to focus the map.
+     *
+     * @deprecated Pass `center` via `mapOptions` instead. The top-level `center`
+     * prop will be removed in a future major version. When both are set,
+     * `mapOptions.center` wins.
+     * @see https://scripts.nuxt.com/docs/migration-guide/v0-to-v1
      */
     center?: google.maps.LatLng | google.maps.LatLngLiteral | `${string},${string}`;
     /**
      * Zoom level for the map (0-21). Reactive: changing this will update the map.
-     * Takes precedence over mapOptions.zoom when provided.
+     *
+     * @deprecated Pass `zoom` via `mapOptions` instead. The top-level `zoom`
+     * prop will be removed in a future major version. When both are set,
+     * `mapOptions.zoom` wins.
+     * @see https://scripts.nuxt.com/docs/migration-guide/v0-to-v1
      */
     zoom?: number;
     /**
@@ -30,19 +38,21 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
      */
     region?: string;
     /**
-     * Defines the language of the map
+     * Defines the language of the map.
      */
     language?: string;
     /**
-     * Defines the version of google maps js API
+     * Defines the version of google maps js API.
      */
     version?: string;
     /**
      * Defines the width of the map.
+     * @default 640
      */
     width?: number | string;
     /**
-     * Defines the height of the map
+     * Defines the height of the map.
+     * @default 400
      */
     height?: number | string;
     /**
@@ -60,122 +70,92 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     };
     /**
      * Manual color mode control. When provided, overrides auto-detection from @nuxtjs/color-mode.
-     * Accepts 'light', 'dark', or a reactive ref.
-     */
-    colorMode?: "light" | "dark";
-}, {
-    readonly googleMaps: import("vue").Ref<typeof google.maps | undefined, typeof google.maps | undefined>;
-    readonly map: ShallowRef<google.maps.Map | undefined>;
-    readonly resolveQueryToLatLng: (query: string) => Promise<google.maps.LatLng | google.maps.LatLngLiteral | undefined>;
-    readonly importLibrary: {
-        (key: "marker"): Promise<google.maps.MarkerLibrary>;
-        (key: "places"): Promise<google.maps.PlacesLibrary>;
-        (key: "geometry"): Promise<google.maps.GeometryLibrary>;
-        (key: "drawing"): Promise<google.maps.DrawingLibrary>;
-        (key: "visualization"): Promise<google.maps.VisualizationLibrary>;
-        (key: string): Promise<any>;
-    };
-}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    error: () => any;
-    ready: (e: {
-        readonly googleMaps: import("vue").Ref<typeof google.maps | undefined, typeof google.maps | undefined>;
-        readonly map: ShallowRef<google.maps.Map | undefined>;
-        readonly resolveQueryToLatLng: (query: string) => Promise<google.maps.LatLng | google.maps.LatLngLiteral | undefined>;
-        readonly importLibrary: {
-            (key: "marker"): Promise<google.maps.MarkerLibrary>;
-            (key: "places"): Promise<google.maps.PlacesLibrary>;
-            (key: "geometry"): Promise<google.maps.GeometryLibrary>;
-            (key: "drawing"): Promise<google.maps.DrawingLibrary>;
-            (key: "visualization"): Promise<google.maps.VisualizationLibrary>;
-            (key: string): Promise<any>;
-        };
-    }) => any;
-}, string, import("vue").PublicProps, Readonly<{
-    /**
-     * Defines the trigger event to load the script.
+     * Accepts 'light' or 'dark'.
      */
-    trigger?: ElementScriptTrigger;
+    colorMode?: 'light' | 'dark';
+}
+export interface ScriptGoogleMapsExpose {
     /**
-     * Defines the Google Maps API key. Must have access to the Static Maps API as well.
+     * A reference to the loaded Google Maps API namespace (`google.maps`), or
+     * `undefined` if not yet loaded.
      */
-    apiKey?: string;
+    mapsApi: ShallowRef<typeof google.maps | undefined>;
     /**
-     * A latitude / longitude of where to focus the map.
+     * A reference to the loaded Google Maps API namespace, or `undefined` if not
+     * yet loaded.
+     *
+     * @deprecated Use `mapsApi` instead. The `googleMaps` alias will be removed
+     * in a future major version.
+     * @see https://scripts.nuxt.com/docs/migration-guide/v0-to-v1
      */
-    center?: google.maps.LatLng | google.maps.LatLngLiteral | `${string},${string}`;
+    googleMaps: ShallowRef<typeof google.maps | undefined>;
     /**
-     * Zoom level for the map (0-21). Reactive: changing this will update the map.
-     * Takes precedence over mapOptions.zoom when provided.
+     * A reference to the Google Map instance, or `undefined` if not yet initialized.
      */
-    zoom?: number;
+    map: ShallowRef<google.maps.Map | undefined>;
     /**
-     * Options for the map.
+     * Utility function to resolve a location query (e.g. "New York, NY") to latitude/longitude coordinates.
+     * Uses a caching mechanism and a server-side proxy to avoid unnecessary client-side API calls.
      */
-    mapOptions?: google.maps.MapOptions;
+    resolveQueryToLatLng: (query: string) => Promise<google.maps.LatLng | google.maps.LatLngLiteral | undefined>;
     /**
-     * Defines the region of the map.
+     * Utility function to dynamically import additional Google Maps libraries (e.g. "marker", "places").
+     * Caches imported libraries for efficient reuse.
      */
-    region?: string;
+    importLibrary: {
+        (key: 'marker'): Promise<google.maps.MarkerLibrary>;
+        (key: 'places'): Promise<google.maps.PlacesLibrary>;
+        (key: 'geometry'): Promise<google.maps.GeometryLibrary>;
+        (key: 'drawing'): Promise<google.maps.DrawingLibrary>;
+        (key: 'visualization'): Promise<google.maps.VisualizationLibrary>;
+        (key: string): Promise<any>;
+    };
+}
+export interface ScriptGoogleMapsEmits {
     /**
-     * Defines the language of the map
+     * Fired when the Google Maps instance is fully loaded and ready to use. Provides access to the maps API.
      */
-    language?: string;
+    ready: [payload: ScriptGoogleMapsExpose];
     /**
-     * Defines the version of google maps js API
+     * Fired when the Google Maps script fails to load.
      */
-    version?: string;
+    error: [];
+}
+export interface ScriptGoogleMapsSlots {
     /**
-     * Defines the width of the map.
+     * Default slot for rendering child components (e.g. markers, info windows) that depend on the map being ready.
      */
-    width?: number | string;
+    default?: () => any;
     /**
-     * Defines the height of the map
+     * Slot displayed while the map is loading. Can be used to show a custom loading indicator.
      */
-    height?: number | string;
+    loading?: () => any;
     /**
-     * Customize the root element attributes.
+     * Slot displayed when the script is awaiting user interaction to load (based on the `trigger` prop).
      */
-    rootAttrs?: HTMLAttributes & ReservedProps & Record<string, unknown>;
+    awaitingLoad?: () => any;
     /**
-     * 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.
+     * Slot displayed if the script fails to load.
      */
-    mapIds?: {
-        light?: string;
-        dark?: string;
-    };
+    error?: () => any;
     /**
-     * Manual color mode control. When provided, overrides auto-detection from @nuxtjs/color-mode.
-     * Accepts 'light', 'dark', or a reactive ref.
+     * Slot displayed as a placeholder before the map is ready. Useful for showing a static map or skeleton.
      */
-    colorMode?: "light" | "dark";
-}> & Readonly<{
+    placeholder?: () => any;
+}
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<ScriptGoogleMapsProps, ScriptGoogleMapsExpose, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    error: () => any;
+    ready: (payload: ScriptGoogleMapsExpose) => any;
+}, string, import("vue").PublicProps, Readonly<ScriptGoogleMapsProps> & Readonly<{
     onError?: (() => any) | undefined;
-    onReady?: ((e: {
-        readonly googleMaps: import("vue").Ref<typeof google.maps | undefined, typeof google.maps | undefined>;
-        readonly map: ShallowRef<google.maps.Map | undefined>;
-        readonly resolveQueryToLatLng: (query: string) => Promise<google.maps.LatLng | google.maps.LatLngLiteral | undefined>;
-        readonly importLibrary: {
-            (key: "marker"): Promise<google.maps.MarkerLibrary>;
-            (key: "places"): Promise<google.maps.PlacesLibrary>;
-            (key: "geometry"): Promise<google.maps.GeometryLibrary>;
-            (key: "drawing"): Promise<google.maps.DrawingLibrary>;
-            (key: "visualization"): Promise<google.maps.VisualizationLibrary>;
-            (key: string): Promise<any>;
-        };
-    }) => any) | undefined;
+    onReady?: ((payload: ScriptGoogleMapsExpose) => any) | undefined;
 }>, {
     trigger: ElementScriptTrigger;
     width: number | string;
     height: number | string;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
-    default?: () => any;
-    placeholder?: () => any;
-    loading?: () => any;
-    awaitingLoad?: () => any;
-    error?: () => any;
-}>;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, ScriptGoogleMapsSlots>;
 type __VLS_WithSlots<T, S> = T & {
     new (): {
         $slots: S;

package/dist/runtime/components/GoogleMaps/ScriptGoogleMaps.vue

@@ -1,18 +1,16 @@
 <script>
+export { MAP_INJECTION_KEY } from "./useGoogleMapsResource";
+</script>
+
+<script setup>
 import { useScriptTriggerElement } from "#nuxt-scripts/composables/useScriptTriggerElement";
 import { useScriptGoogleMaps } from "#nuxt-scripts/registry/google-maps";
 import { scriptRuntimeConfig, scriptsPrefix } from "#nuxt-scripts/utils";
 import { defu } from "defu";
 import { tryUseNuxtApp, useHead, useRuntimeConfig } from "nuxt/app";
-import { computed, onBeforeUnmount, onMounted, provide, ref, shallowRef, toRaw, useAttrs, watch } from "vue";
+import { computed, onBeforeUnmount, onMounted, provide, ref, shallowRef, toRaw, useAttrs, useTemplateRef, watch } from "vue";
 import ScriptAriaLoadingIndicator from "../ScriptAriaLoadingIndicator.vue";
-import { MAP_INJECTION_KEY } from "./useGoogleMapsResource";
-const DIGITS_ONLY_RE = /^\d+$/;
-const DIGITS_PX_RE = /^\d+px$/i;
-export { MAP_INJECTION_KEY } from "./useGoogleMapsResource";
-</script>
-
-<script setup>
+import { defineDeprecatedAlias, MAP_INJECTION_KEY, waitForMapsReady, warnDeprecatedTopLevelMapProps } from "./useGoogleMapsResource";
 const props = defineProps({
   trigger: { type: [String, Array, Boolean], required: false, default: ["mouseenter", "mouseover", "mousedown"] },
   apiKey: { type: String, required: false },
@@ -30,23 +28,21 @@ const props = defineProps({
 });
 const emits = defineEmits(["ready", "error"]);
 defineSlots();
+const DIGITS_ONLY_RE = /^\d+$/;
+const DIGITS_PX_RE = /^\d+px$/i;
 const apiKey = props.apiKey || scriptRuntimeConfig("googleMaps")?.apiKey;
 const runtimeConfig = useRuntimeConfig();
-const nuxtApp = tryUseNuxtApp();
-const nuxtColorMode = nuxtApp?.$colorMode;
-const currentColorMode = computed(() => {
-  if (props.colorMode)
-    return props.colorMode;
-  if (nuxtColorMode?.value)
-    return nuxtColorMode.value === "dark" ? "dark" : "light";
-  return "light";
+const nuxtColorMode = computed(() => {
+  const value = tryUseNuxtApp()?.$colorMode?.value;
+  return value === "dark" || value === "light" ? value : void 0;
 });
+const currentColorMode = computed(() => props.colorMode || nuxtColorMode.value || "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();
+const mapsApi = shallowRef();
 if (import.meta.dev) {
   if (!apiKey)
     throw new Error("GoogleMaps requires an API key. Enable it in your nuxt.config:\n\n  scripts: {\n    registry: {\n      googleMaps: true\n    }\n  }\n\nThen set NUXT_PUBLIC_SCRIPTS_GOOGLE_MAPS_API_KEY in your .env file.\n\nAlternatively, pass `api-key` directly on the <ScriptGoogleMaps> component (note: this exposes the key client-side).");
@@ -62,9 +58,10 @@ if (import.meta.dev) {
     if (prop in attrs)
       console.warn(`[nuxt-scripts] <ScriptGoogleMaps> prop "${prop}" was removed in v1. ${message} See https://scripts.nuxt.com/docs/migration-guide/v0-to-v1`);
   }
+  warnDeprecatedTopLevelMapProps({ center: props.center, zoom: props.zoom });
 }
-const rootEl = ref();
-const mapEl = ref();
+const rootEl = useTemplateRef("rootEl");
+const mapEl = useTemplateRef("mapEl");
 const centerOverride = ref();
 const trigger = useScriptTriggerElement({ trigger: props.trigger, el: rootEl });
 const { load, status, onLoaded } = useScriptGoogleMaps({
@@ -78,12 +75,14 @@ const { load, status, onLoaded } = useScriptGoogleMaps({
 });
 const options = computed(() => {
   const mapId = props.mapOptions?.styles ? void 0 : currentMapId.value || "map";
-  return defu({ center: centerOverride.value, mapId, zoom: props.zoom }, props.mapOptions, {
-    center: props.center,
-    zoom: 15
-  });
+  return defu(
+    { center: centerOverride.value, mapId },
+    props.mapOptions,
+    { center: props.center, zoom: props.zoom },
+    { zoom: 15 }
+  );
 });
-const ready = ref(false);
+const isMapReady = ref(false);
 const map = shallowRef();
 function isLocationQuery(s) {
   return typeof s === "string" && (s.split(",").length > 2 || s.includes("+"));
@@ -108,29 +107,25 @@ async function resolveQueryToLatLng(query) {
     }
     throw new Error(`No location found for ${query}`);
   }
-  return new Promise(async (resolve, reject) => {
-    if (!mapsApi.value) {
-      await load();
-      await new Promise((resolve2) => {
-        const _ = watch(mapsApi, () => {
-          _();
-          resolve2();
-        });
-      });
-    }
-    const placesService = new mapsApi.value.places.PlacesService(map.value);
-    placesService.findPlaceFromQuery({
-      query,
-      fields: ["name", "geometry"]
-    }, (results, status2) => {
-      if (status2 === "OK" && results?.[0]?.geometry?.location)
-        return resolve(results[0].geometry.location);
-      return reject(new Error(`No location found for ${query}`));
-    });
-  }).then((res) => {
-    queryToLatLngCache.set(query, res);
-    return res;
+  await waitForMapsReady({ mapsApi, map, status, load });
+  const placesService = new mapsApi.value.places.PlacesService(map.value);
+  const result = await new Promise((resolve, reject) => {
+    placesService.findPlaceFromQuery(
+      {
+        query,
+        fields: ["name", "geometry"]
+      },
+      (results, status2) => {
+        if (status2 === "OK" && results?.[0]?.geometry?.location) {
+          resolve(results[0].geometry.location);
+        } else {
+          reject(new Error(`No location found for ${query}`));
+        }
+      }
+    );
   });
+  queryToLatLngCache.set(query, result);
+  return result;
 }
 const libraries = /* @__PURE__ */ new Map();
 function importLibrary(key) {
@@ -152,13 +147,25 @@ function importLibrary(key) {
   libraries.set(key, cached);
   return cached;
 }
-const googleMaps = {
+const exposed = {
+  mapsApi,
+  // Plain alias for production. In dev, replaced below with a getter that
+  // emits a one-shot deprecation warning. Both forms return the same
+  // shallow ref as `mapsApi`.
   googleMaps: mapsApi,
   map,
   resolveQueryToLatLng,
   importLibrary
 };
-defineExpose(googleMaps);
+if (import.meta.dev) {
+  defineDeprecatedAlias(
+    exposed,
+    "googleMaps",
+    "mapsApi",
+    '[nuxt-scripts] <ScriptGoogleMaps> expose key "googleMaps" is deprecated; use "mapsApi" instead. See https://scripts.nuxt.com/docs/migration-guide/v0-to-v1'
+  );
+}
+defineExpose(exposed);
 let activeInfoWindow;
 provide(MAP_INJECTION_KEY, {
   map,
@@ -171,9 +178,9 @@ provide(MAP_INJECTION_KEY, {
   }
 });
 onMounted(() => {
-  watch(ready, (v) => {
+  watch(isMapReady, (v) => {
     if (v) {
-      emits("ready", googleMaps);
+      emits("ready", exposed);
     }
   });
   watch(status, (v) => {
@@ -191,13 +198,13 @@ onMounted(() => {
     if (map.value && zoom != null)
       map.value.setZoom(zoom);
   });
-  watch([() => options.value.center, ready, map], async (next) => {
+  watch([() => options.value.center, isMapReady, map], async (next) => {
     if (!map.value) {
       return;
     }
     let center = toRaw(next[0]);
     if (center) {
-      if (isLocationQuery(center) && ready.value) {
+      if (isLocationQuery(center) && isMapReady.value) {
         center = await resolveQueryToLatLng(center);
       }
       const current = map.value.getCenter();
@@ -223,9 +230,10 @@ onMounted(() => {
     map.value = new mapsApi.value.Map(mapEl.value, _options);
     if (center && isLocationQuery(center)) {
       centerOverride.value = await resolveQueryToLatLng(center);
-      map.value?.setCenter(centerOverride.value);
+      if (centerOverride.value)
+        map.value?.setCenter(centerOverride.value);
     }
-    ready.value = true;
+    isMapReady.value = true;
   });
 });
 if (import.meta.server) {
@@ -280,9 +288,9 @@ onBeforeUnmount(() => {
 
 <template>
   <div ref="rootEl" v-bind="rootAttrs">
-    <div v-show="ready" ref="mapEl" :style="{ width: '100%', height: '100%', maxWidth: '100%' }" />
-    <slot v-if="!ready" name="placeholder" />
-    <slot v-if="status !== 'awaitingLoad' && !ready" name="loading">
+    <div v-show="isMapReady" ref="mapEl" :style="{ width: '100%', height: '100%', maxWidth: '100%' }" />
+    <slot v-if="!isMapReady" name="placeholder" />
+    <slot v-if="status !== 'awaitingLoad' && !isMapReady" name="loading">
       <ScriptAriaLoadingIndicator />
     </slot>
     <slot v-if="status === 'awaitingLoad'" name="awaitingLoad" />