refactor(google-maps)!: rename googleMaps expose to mapsApi

[harlan-zw]

🔗 Linked issue

Related to #689 (PR C in the umbrella split-up plan).

❓ Type of change

• 📖 Documentation
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

Renames the template-ref expose key on <ScriptGoogleMaps> from googleMaps to mapsApi, which more accurately reflects what it holds (the google.maps API namespace, not the component itself). The old key is preserved as a deprecated alias backed by an accessor that fires a one-shot dev-mode warning, so existing template-ref consumers keep working without breakage.

<ScriptGoogleMapsOverlayView> gets the same treatment: overlay becomes overlayView, with overlay retained as a deprecated alias.

⚠️ Breaking Changes

Strictly speaking this is an additive change in dev mode (both keys still work) and an additive change in prod mode (both keys still work). The breaking-change marker is conservative because:

• The canonical name in ScriptGoogleMapsExpose / ScriptGoogleMapsOverlayViewExpose is now mapsApi / overlayView. TypeScript users who annotated ScriptGoogleMapsExpose directly may see new required-property errors if they construct the object themselves. The interface still includes the old keys as deprecated, so destructuring patterns (const { googleMaps } = exposed) still typecheck.
• Reading the legacy key in dev now logs a one-shot warning per component instance.

📝 Migration

 const mapRef = ref()
 onMounted(() => {
-  console.log(mapRef.value?.googleMaps)
+  console.log(mapRef.value?.mapsApi)
 })

 const overlayRef = ref()
 onMounted(() => {
-  console.log(overlayRef.value?.overlay)
+  console.log(overlayRef.value?.overlayView)
 })

🛠 Implementation notes

• Added a generic defineDeprecatedAlias helper in useGoogleMapsResource that replaces a data property with an accessor that fires a one-shot warning
• Both call sites wrap the helper in if (import.meta.dev), so production builds skip the getter entirely and the alias stays a plain data property pointing at the canonical ref. No runtime overhead in prod.
• The ready event payload still uses ScriptGoogleMapsExpose, so consumers gain mapsApi as an additive property without breakage.

🛡 Protected behaviours

All v1 protected behaviours are untouched:

• Skip-if-equal setCenter watcher
• setOptions exclusion of zoom/center
• defineModel('open', { default: undefined }) on OverlayView
• OverlayView data-state attribute
• InfoWindow group close

🧪 Tests

Added 9 unit tests in test/unit/google-maps-components.test.ts covering both renames:

• Alias and canonical key return the same shallow ref
• Reading the alias fires the dev warning exactly once (one-shot)
• Repeated reads do not spam the console
• Reading the canonical key never warns
• Live updates flow through both keys (since they share the underlying ShallowRef)

All 84 google-maps-* unit tests pass; lint and typecheck clean.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
scripts-playground	Ready	Preview, Comment	Apr 9, 2026 1:46pm

[pkg-pr-new]

Open in StackBlitz

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

commit: afc20b1

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b7f60bf8-87ed-40d8-9061-84592088bbfc

📥 Commits

Reviewing files that changed from the base of the PR and between bf560fd and afc20b1.

📒 Files selected for processing (6)

• docs/content/docs/4.migration-guide/1.v0-to-v1.md
• docs/content/scripts/google-maps/2.api/1.script-google-maps.md
• packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
• packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
• packages/script/src/runtime/components/GoogleMaps/useGoogleMapsResource.ts
• test/unit/google-maps-components.test.ts

---

📝 Walkthrough

Walkthrough

This pull request refactors the Google Maps component API by renaming two exposed template-ref keys to improve naming clarity. The ScriptGoogleMaps component's googleMaps ref is renamed to mapsApi, and the ScriptGoogleMapsOverlayView component's overlay ref is renamed to overlayView. Backward compatibility is maintained by keeping the original names as deprecated aliases that emit one-time dev-mode warnings on first access. A new utility function defineDeprecatedAlias is introduced to manage the deprecation warning behavior, and comprehensive test coverage and documentation updates accompany the implementation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: renaming the googleMaps expose to mapsApi in the google-maps component.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, covering the refactoring rationale, breaking changes, migration steps, implementation details, and test coverage.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/google-maps-rename-expose-mapsapi

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}