fix: Add missing deprecation warnings for next-intl@4.0 (#1485)

Adds missing deprecation warnings:
1. Warn when `locale` parameter is accessed in `getRequestConfig`
([ref](https://next-intl-docs.vercel.app/blog/next-intl-3-22#await-request-locale))
1. Warn when no `locale` was returned from `getRequestConfig`
([ref](https://next-intl-docs.vercel.app/blog/next-intl-3-22#await-request-locale))
2. Warn when using `next-intl` in a Client Component without a
`NextIntlClientProvider` ancestor being present
([ref](#1541))

Author: amannn

packages/next-intl/.size-limit.ts

@@ -71,7 +71,7 @@ const config: SizeLimitConfig = [
     name: "import * from 'next-intl' (react-client, ESM)",
     path: 'dist/esm/index.react-client.js',
     import: '*',
-    limit: '14.245 kB'
+    limit: '14.365 kB'
   },
   {
     name: "import {NextIntlProvider} from 'next-intl' (react-client, ESM)",

packages/next-intl/CHANGELOG.md

@@ -1027,4 +1027,4 @@ Please refer to [the release notes](https://next-intl-docs.vercel.app/blog/next-
 
 ## [1.3.3](https://github.com/amannn/next-intl/compare/v1.3.2...v1.3.3) (2021-02-09)
 
-**Note:** Version bump only for package next-intl
+**Note:** Version bump only for package next-intl

packages/next-intl/src/react-client/useLocale.tsx

@@ -3,6 +3,8 @@ import {useParams} from 'next/navigation';
 import {useLocale as useBaseLocale} from 'use-intl/_useLocale';
 import {LOCALE_SEGMENT_NAME} from '../shared/constants';
 
+let hasWarnedForParams = false;
+
 export default function useLocale(): string {
   // The types aren't entirely correct here. Outside of Next.js
   // `useParams` can be called, but the return type is `null`.
@@ -16,6 +18,12 @@ export default function useLocale(): string {
     locale = useBaseLocale();
   } catch (error) {
     if (typeof params?.[LOCALE_SEGMENT_NAME] === 'string') {
+      if (process.env.NODE_ENV !== 'production' && !hasWarnedForParams) {
+        console.warn(
+          'Deprecation warning: `useLocale` has returned a default from `useParams().locale` since no `NextIntlClientProvider` ancestor was found for the calling component. This behavior will be removed in the next major version. Please ensure all Client Components that use `next-intl` are wrapped in a `NextIntlClientProvider`.'
+        );
+        hasWarnedForParams = true;
+      }
       locale = params[LOCALE_SEGMENT_NAME];
     } else {
       throw error;

packages/next-intl/src/server/react-server/getConfig.tsx

@@ -11,6 +11,9 @@ import {getRequestLocale as getRequestLocaleLegacy} from './RequestLocaleLegacy'
 import createRequestConfig from './createRequestConfig';
 import {GetRequestConfigParams} from './getRequestConfig';
 
+let hasWarnedForMissingReturnedLocale = false;
+let hasWarnedForAccessedLocaleParam = false;
+
 // Make sure `now` is consistent across the request in case none was configured
 function getDefaultNowImpl() {
   return new Date();
@@ -49,6 +52,15 @@ See also: https://next-intl.dev/docs/usage/configuration#i18n-request
     // `locale` (either in a single-language workflow or because the locale is
     // read from the user settings), don't attempt to read the request locale.
     get locale() {
+      if (
+        process.env.NODE_ENV !== 'production' &&
+        !hasWarnedForAccessedLocaleParam
+      ) {
+        console.warn(
+          `\nThe \`locale\` parameter in \`getRequestConfig\` is deprecated, please switch to \`await requestLocale\`. See https://next-intl.dev/blog/next-intl-3-22#await-request-locale\n`
+        );
+        hasWarnedForAccessedLocaleParam = true;
+      }
       return localeOverride || getRequestLocaleLegacy();
     },
 
@@ -64,15 +76,28 @@ See also: https://next-intl.dev/docs/usage/configuration#i18n-request
     result = await result;
   }
 
-  const locale = result.locale || (await params.requestLocale);
+  let locale = result.locale;
 
   if (!locale) {
-    if (process.env.NODE_ENV !== 'production') {
+    if (
+      process.env.NODE_ENV !== 'production' &&
+      !hasWarnedForMissingReturnedLocale
+    ) {
       console.error(
-        `\nUnable to find \`next-intl\` locale because the middleware didn't run on this request and no \`locale\` was returned in \`getRequestConfig\`. See https://next-intl.dev/docs/routing/middleware#unable-to-find-locale. The \`notFound()\` function will be called as a result.\n`
+        `\nA \`locale\` is expected to be returned from \`getRequestConfig\`, but none was returned. This will be an error in the next major version of next-intl.\n\nSee: https://next-intl.dev/blog/next-intl-3-22#await-request-locale\n`
       );
+      hasWarnedForMissingReturnedLocale = true;
+    }
+
+    locale = await params.requestLocale;
+    if (!locale) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error(
+          `\nUnable to find \`next-intl\` locale because the middleware didn't run on this request and no \`locale\` was returned in \`getRequestConfig\`. See https://next-intl.dev/docs/routing/middleware#unable-to-find-locale. The \`notFound()\` function will be called as a result.\n`
+        );
+      }
+      notFound();
     }
-    notFound();
   }
 
   return {

packages/next-intl/src/server/react-server/getRequestConfig.tsx

@@ -2,14 +2,7 @@ import type {IntlConfig} from 'use-intl/core';
 
 export type RequestConfig = Omit<IntlConfig, 'locale'> & {
   /**
-   * Instead of reading a `requestLocale` from the argument that's passed to the
-   * function within `getRequestConfig`, you can include a locale as part of the
-   * returned request configuration.
-   *
-   * This can be helpful for the following use cases:
-   * - Apps that only support a single language
-   * - Apps where the locale should be read from user settings instead of the pathname
-   * - Providing a fallback locale in case the locale was not matched by the middleware
+   * @see https://next-intl.dev/docs/usage/configuration#i18n-request
    **/
   locale?: IntlConfig['locale'];
 };