fix!: nuxt context injected function types (#3098)

docs/content/docs/5.v9/2.guide/19.breaking-changes-in-v9.md

@@ -64,3 +64,17 @@ Some properties have changed or swapped names to better fit their functionality,
 ## SEO - `useLocaleHead`
 
 We have added a `addLangAttribute` property to the options parameter of `useLocaleHead` and `$localeHead`, originally this was not configurable on its own. If you want to keep the same behavior, if you were passing `addSeoAttributes`, you will also have to pass `addLangAttribute: true`. See [`useLocaleHead`](/docs/v9/api#useLocaleHead)
+
+## Nuxt context functions
+
+In v8 both the types and name of the injected context functions (such as `$localePath`, `$switchLocalePath` and [more](/docs/v9/api/nuxt)) did not work as intended. You may have found that these functions worked when using them without prefix (`$`) even when not assigning these functions from a composable. 
+
+The types and names have been fixed in v9, if you have been using the unprefixed functions globally (without composable) in your project you will have to prefix these functions as they were originally intended.
+
+- `getRouteBaseName` -> `$getRouteBaseName`
+- `resolveRoute` -> `$resolveRoute`
+- `localePath` -> `$localePath`
+- `localeRoute` -> `$localeRoute`
+- `localeLocation` -> `$localeLocation`
+- `switchLocalePath` -> `$switchLocalePath`
+- `localeHead` -> `$localeHead`

playground/pages/[...catch].vue

@@ -19,7 +19,7 @@ definePageMeta({
     <p>This page is catch all: '{{ route.params }}'</p>
     <nav>
       <span v-for="locale in availableLocales" :key="locale.code">
-        <NuxtLink :to="switchLocalePath(locale.code) || ''">{{ locale.name }}</NuxtLink> |
+        <NuxtLink :to="$switchLocalePath(locale.code) || ''">{{ locale.name }}</NuxtLink> |
       </span>
     </nav>
   </div>

playground/pages/about/index.vue

@@ -40,11 +40,11 @@ export default defineComponent({
 <template>
   <div>
     <nav>
-      <NuxtLink :to="localePath('/')">Back to Home</NuxtLink>
+      <NuxtLink :to="$localePath('/')">Back to Home</NuxtLink>
     </nav>
     <nav>
       <span v-for="locale in availableLocales" :key="locale.code">
-        <NuxtLink :to="switchLocalePath(locale.code) || ''">{{ locale.name }}</NuxtLink> |
+        <NuxtLink :to="$switchLocalePath(locale.code) || ''">{{ locale.name }}</NuxtLink> |
       </span>
     </nav>
     <p>hello</p>
@@ -54,6 +54,6 @@ export default defineComponent({
       </span>
     </nav>
     <p>{{ switchableLocale }}</p>
-    <p>{{ localeHead({ addSeoAttributes: true }) }}</p>
+    <p>{{ $localeHead({ addSeoAttributes: true }) }}</p>
   </div>
 </template>

playground/pages/category/[id].vue

@@ -19,7 +19,7 @@ definePageMeta({
     <p>This is cateory page on '{{ route.params.id }}'</p>
     <nav>
       <span v-for="locale in availableLocales" :key="locale.code">
-        <NuxtLink :to="switchLocalePath(locale.code) || ''">{{ locale.name }}</NuxtLink> |
+        <NuxtLink :to="$switchLocalePath(locale.code) || ''">{{ locale.name }}</NuxtLink> |
       </span>
       <i18n-t keypath="hello">
         <template #name>nuxtjs/i18n</template>

specs/fixtures/basic/pages/blog/index.vue

@@ -1,6 +1,6 @@
 <template>
   <div>
     <p>This is blog index page</p>
-    <NuxtLink id="link-blog-article" exact :to="localePath('blog-article')">article</NuxtLink>
+    <NuxtLink id="link-blog-article" exact :to="$localePath('blog-article')">article</NuxtLink>
   </div>
 </template>

specs/fixtures/basic/pages/define-i18n-route-false.vue

@@ -1,7 +1,7 @@
 <template>
   <div>
     <h1 id="disable-route-text">Page with disabled localized route</h1>
-    <nuxt-link id="goto-home" :to="localePath('/')"> Goto Home </nuxt-link>
+    <nuxt-link id="goto-home" :to="$localePath('/')"> Goto Home </nuxt-link>
   </div>
 </template>
 

specs/fixtures/different_domains/pages/blog/index.vue

@@ -1,6 +1,6 @@
 <template>
   <div>
     <p>This is blog index page</p>
-    <NuxtLink id="link-blog-article" exact :to="localePath('blog-article')">article</NuxtLink>
+    <NuxtLink id="link-blog-article" exact :to="$localePath('blog-article')">article</NuxtLink>
   </div>
 </template>

specs/fixtures/multi_domains_locales/pages/blog/index.vue

@@ -1,6 +1,6 @@
 <template>
   <div>
     <p>This is blog index page</p>
-    <NuxtLink id="link-blog-article" exact :to="localePath('blog-article')">article</NuxtLink>
+    <NuxtLink id="link-blog-article" exact :to="$localePath('blog-article')">article</NuxtLink>
   </div>
 </template>

src/runtime/injections.ts

@@ -0,0 +1,68 @@
+import type {
+  LocaleHeadFunction,
+  LocalePathFunction,
+  LocaleRouteFunction,
+  RouteBaseNameFunction,
+  SwitchLocalePathFunction
+} from '#i18n'
+import type {
+  getRouteBaseName,
+  localeHead,
+  localePath,
+  localeRoute,
+  switchLocalePath
+} from './routing/compatibles/index'
+
+export type NuxtI18nPluginInjections = {
+  /**
+   * Returns base name of current (if argument not provided) or passed in route.
+   *
+   * @remarks
+   * Base name is name of the route without locale suffix and other metadata added by nuxt i18n module
+   *
+   * @param givenRoute - A route.
+   *
+   * @returns The route base name. if cannot get, `undefined` is returned.
+   */
+  getRouteBaseName: (...args: Parameters<RouteBaseNameFunction>) => ReturnType<typeof getRouteBaseName>
+  /**
+   * Returns localized path for passed in route.
+   *
+   * @remarks
+   * If locale is not specified, uses current locale.
+   *
+   * @param route - A route.
+   * @param locale - A locale, optional.
+   *
+   * @returns A path of the current route.
+   */
+  localePath: (...args: Parameters<LocalePathFunction>) => ReturnType<typeof localePath>
+  /**
+   * Returns localized route for passed in `route` parameters.
+   *
+   * @remarks
+   * If `locale` is not specified, uses current locale.
+   *
+   * @param route - A route.
+   * @param locale - A {@link Locale | locale}, optional.
+   *
+   * @returns A route. if cannot resolve, `undefined` is returned.
+   */
+  localeRoute: (...args: Parameters<LocaleRouteFunction>) => ReturnType<typeof localeRoute>
+  /**
+   * Returns localized head properties for locale-related aspects.
+   *
+   * @param options - An options object, see `I18nHeadOptions`.
+   *
+   * @returns The localized head properties.
+   */
+  localeHead: (...args: Parameters<LocaleHeadFunction>) => ReturnType<typeof localeHead>
+  /**
+   * Returns path of the current route for specified locale
+   *
+   * @param locale - A {@link Locale}
+   *
+   * @returns A path of the current route
+   */
+  switchLocalePath: (...args: Parameters<SwitchLocalePathFunction>) => ReturnType<typeof switchLocalePath>
+}

src/runtime/plugins/i18n.ts

@@ -33,18 +33,24 @@ import { extendI18n, createLocaleFromRouteGetter } from '../routing/extends'
 import { setLocale, getLocale, mergeLocaleMessage, setLocaleProperty } from '../compatibility'
 import { createLogger } from 'virtual:nuxt-i18n-logger'
 
+import type { NuxtI18nPluginInjections } from '../injections'
 import type { Locale, I18nOptions } from 'vue-i18n'
 import type { NuxtApp } from '#app'
-import type { getRouteBaseName, localePath, localeRoute, switchLocalePath, localeHead } from '../routing/compatibles'
-import type {
-  LocaleHeadFunction,
-  LocalePathFunction,
-  LocaleRouteFunction,
-  RouteBaseNameFunction,
-  SwitchLocalePathFunction
-} from '../composables'
-
-export default defineNuxtPlugin({
+
+// from https://github.com/nuxt/nuxt/blob/2466af53b0331cdb8b17c2c3b08675c5985deaf3/packages/nuxt/src/core/templates.ts#L152
+type Decorate<T extends Record<string, unknown>> = { [K in keyof T as K extends string ? `$${K}` : never]: T[K] }
+
+// TODO: use @nuxt/module-builder to stub/prepare types
+declare module '#app' {
+  interface NuxtApp extends Decorate<NuxtI18nPluginInjections> {}
+}
+
+// declare module 'vue' {
+//   interface ComponentCustomProperties extends Decorate<NuxtI18nPluginInjections> {}
+// }
+
+// `NuxtI18nPluginInjections` should not have properties prefixed with `$`
+export default defineNuxtPlugin<NuxtI18nPluginInjections>({
   name: 'i18n:plugin',
   parallel: parallelPlugin,
   async setup(nuxt) {
@@ -383,59 +389,3 @@ export default defineNuxtPlugin({
     )
   }
 })
-
-declare module '#app' {
-  interface NuxtApp {
-    /**
-     * Returns base name of current (if argument not provided) or passed in route.
-     *
-     * @remarks
-     * Base name is name of the route without locale suffix and other metadata added by nuxt i18n module
-     *
-     * @param givenRoute - A route.
-     *
-     * @returns The route base name. if cannot get, `undefined` is returned.
-     */
-    $getRouteBaseName: (...args: Parameters<RouteBaseNameFunction>) => ReturnType<typeof getRouteBaseName>
-    /**
-     * Returns localized path for passed in route.
-     *
-     * @remarks
-     * If locale is not specified, uses current locale.
-     *
-     * @param route - A route.
-     * @param locale - A locale, optional.
-     *
-     * @returns A path of the current route.
-     */
-    $localePath: (...args: Parameters<LocalePathFunction>) => ReturnType<typeof localePath>
-    /**
-     * Returns localized route for passed in `route` parameters.
-     *
-     * @remarks
-     * If `locale` is not specified, uses current locale.
-     *
-     * @param route - A route.
-     * @param locale - A {@link Locale | locale}, optional.
-     *
-     * @returns A route. if cannot resolve, `undefined` is returned.
-     */
-    $localeRoute: (...args: Parameters<LocaleRouteFunction>) => ReturnType<typeof localeRoute>
-    /**
-     * Returns localized head properties for locale-related aspects.
-     *
-     * @param options - An options object, see `I18nHeadOptions`.
-     *
-     * @returns The localized head properties.
-     */
-    $localeHead: (...args: Parameters<LocaleHeadFunction>) => ReturnType<typeof localeHead>
-    /**
-     * Returns path of the current route for specified locale
-     *
-     * @param locale - A {@link Locale}
-     *
-     * @returns A path of the current route
-     */
-    $switchLocalePath: (...args: Parameters<SwitchLocalePathFunction>) => ReturnType<typeof switchLocalePath>
-  }
-}

src/runtime/routing/extends/i18n.ts

@@ -89,13 +89,13 @@ export function extendI18n(i18n: I18n, { extendComposer, extendComposerInstance
       const common = initCommonComposableOptions(i18n)
       app.mixin({
         methods: {
-          getRouteBaseName: wrapComposable(getRouteBaseName, common),
-          resolveRoute: wrapComposable(resolveRoute, common),
-          localePath: wrapComposable(localePath, common),
-          localeRoute: wrapComposable(localeRoute, common),
-          localeLocation: wrapComposable(localeLocation, common),
-          switchLocalePath: wrapComposable(switchLocalePath, common),
-          localeHead: wrapComposable(localeHead, common)
+          $getRouteBaseName: wrapComposable(getRouteBaseName, common),
+          $resolveRoute: wrapComposable(resolveRoute, common),
+          $localePath: wrapComposable(localePath, common),
+          $localeRoute: wrapComposable(localeRoute, common),
+          $localeLocation: wrapComposable(localeLocation, common),
+          $switchLocalePath: wrapComposable(switchLocalePath, common),
+          $localeHead: wrapComposable(localeHead, common)
         }
       })
     }