Cleanup:

 - Allow to override the time zone per invocation
 - Docs: Mention capability to reference formats by name, specify custom anchors, more compact formatting in example
 - Bump sizes

Author: amannn

docs/pages/docs/usage/dates-times.mdx

@@ -5,7 +5,7 @@ import PartnerContentLink from 'components/PartnerContentLink';
 
 The formatting of dates and times varies greatly between locales (e.g. "Apr 24, 2023" in `en-US` vs. "24 квіт. 2023 р." in `uk-UA`). By using the formatting capabilities of `next-intl`, you can handle i18n differences in your Next.js app automatically.
 
-## Formatting dates and times
+## Formatting dates and times [#dates-times]
 
 You can format plain dates that are not part of a message with the `dateTime` function that is returned from the `useFormatter` hook:
 
@@ -30,6 +30,12 @@ function Component() {
 
 See [the MDN docs about `DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#Using_options) to learn more about the options that you can provide to the `dateTime` function or [try the interactive explorer for `Intl.DateTimeFormat`](https://www.intl-explorer.com/DateTimeFormat).
 
+If you have [global formats](/docs/usage/configuration#formats) configured, you can reference them by passing a name as the second argument:
+
+```js
+format.dateTime(dateTime, 'short');
+```
+
 <details>
 <summary>How can I parse dates or manipulate them?</summary>
 
@@ -49,7 +55,7 @@ const twoDaysAgo = subDays(date, 2);
 
 </details>
 
-## Formatting relative time
+## Formatting relative times [#relative-times]
 
 You can format plain dates that are not part of a message with the `relativeTime` function:
 
@@ -124,28 +130,33 @@ function Component() {
 }
 ```
 
-## Formatting time ranges
+## Formatting date and time ranges [#date-time-ranges]
 
-You can format date ranges with the `dateTimeRange` function:
+You can format ranges of dates and times with the `dateTimeRange` function:
 
 ```js
 import {useFormatter} from 'next-intl';
 
 function Component() {
   const format = useFormatter();
   const dateTimeA = new Date('2020-11-20T08:30:00.000Z');
-  const dateTimeB = new Date('2020-11-24T08:30:00.000Z');
+  const dateTimeB = new Date('2021-01-24T08:30:00.000Z');
 
+  // Renders "Nov 20, 2020 – Jan 24, 2021"
   format.dateTimeRange(dateTimeA, dateTimeB, {
-    weekday: 'long',
     year: 'numeric',
-    month: 'long',
+    month: 'short',
     day: 'numeric'
   });
-  // this will render "Friday, November 20 – Tuesday, November 24, 2020"
 }
 ```
 
+If you have [global formats](/docs/usage/configuration#formats) configured, you can reference them by passing a name as the trailing argument:
+
+```js
+format.dateTimeRange(dateTimeA, dateTimeB, 'short');
+```
+
 ## Dates and times within messages
 
 Dates and times can be embedded within messages by using the ICU syntax.

docs/pages/docs/usage/numbers.mdx

@@ -28,6 +28,12 @@ function Component() {
 
 See [the MDN docs about `NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat#Using_options) to learn more about the options you can pass to the `number` function or [try the interactive explorer for `Intl.NumberFormat`](https://www.intl-explorer.com/NumberFormat).
 
+If you have [global formats](/docs/usage/configuration#formats) configured, you can reference them by passing a name as the second argument:
+
+```js
+format.number(499.9, 'precise');
+```
+
 ## Numbers within messages
 
 Numbers can be embedded within messages by using the ICU syntax.

packages/next-intl/package.json

@@ -114,11 +114,11 @@
   "size-limit": [
     {
       "path": "dist/production/index.react-client.js",
-      "limit": "12.99 KB"
+      "limit": "13.055 KB"
     },
     {
       "path": "dist/production/index.react-server.js",
-      "limit": "13.75 KB"
+      "limit": "13.765 KB"
     },
     {
       "path": "dist/production/navigation.react-client.js",
@@ -134,7 +134,7 @@
     },
     {
       "path": "dist/production/server.react-server.js",
-      "limit": "12.945 KB"
+      "limit": "13.05 KB"
     },
     {
       "path": "dist/production/middleware.js",

packages/use-intl/package.json

@@ -90,7 +90,7 @@
   "size-limit": [
     {
       "path": "dist/production/index.js",
-      "limit": "12.5 kB"
+      "limit": "12.565 kB"
     }
   ]
 }

packages/use-intl/src/core/createFormatter.tsx

@@ -78,21 +78,25 @@ export default function createFormatter({
   onError = defaultOnError,
   timeZone: globalTimeZone
 }: Props) {
-  function applyGlobalTimeZone(options?: DateTimeFormatOptions) {
-    if (globalTimeZone) {
-      options = {...options, timeZone: globalTimeZone};
-    } else {
-      onError(
-        new IntlError(
-          IntlErrorCode.ENVIRONMENT_FALLBACK,
-          process.env.NODE_ENV !== 'production'
-            ? `The \`timeZone\` parameter wasn't provided and there is no global default configured. Consider adding a global default to avoid markup mismatches caused by environment differences. Learn more: https://next-intl-docs.vercel.app/docs/configuration#time-zone`
-            : undefined
-        )
-      );
+  function applyTimeZone(options?: DateTimeFormatOptions) {
+    if (!options?.timeZone) {
+      if (globalTimeZone) {
+        options = {...options, timeZone: globalTimeZone};
+      } else {
+        onError(
+          new IntlError(
+            IntlErrorCode.ENVIRONMENT_FALLBACK,
+            process.env.NODE_ENV !== 'production'
+              ? `The \`timeZone\` parameter wasn't provided and there is no global default configured. Consider adding a global default to avoid markup mismatches caused by environment differences. Learn more: https://next-intl-docs.vercel.app/docs/configuration#time-zone`
+              : undefined
+          )
+        );
+      }
     }
+
     return options;
   }
+
   function resolveFormatOrOptions<Options>(
     typeFormats: Record<string, Options> | undefined,
     formatOrOptions?: string | Options
@@ -153,8 +157,7 @@ export default function createFormatter({
       formatOrOptions,
       formats?.dateTime,
       (options) => {
-        options = applyGlobalTimeZone(options);
-
+        options = applyTimeZone(options);
         return new Intl.DateTimeFormat(locale, options).format(value);
       },
       () => String(value)
@@ -166,16 +169,15 @@ export default function createFormatter({
     start: Date | number,
     /** If a number is supplied, this is interpreted as a UTC timestamp. */
     end: Date | number,
-    /** If a time zone is supplied, the `value` is converted to that time zone.
+    /** If a time zone is supplied, the values are converted to that time zone.
      * Otherwise the user time zone will be used. */
     formatOrOptions?: string | DateTimeFormatOptions
   ) {
     return getFormattedValue(
       formatOrOptions,
       formats?.dateTime,
       (options) => {
-        options = applyGlobalTimeZone(options);
-
+        options = applyTimeZone(options);
         return new Intl.DateTimeFormat(locale, options).formatRange(start, end);
       },
       () => [dateTime(start), dateTime(end)].join(' – ')

packages/use-intl/test/core/createFormatter.test.tsx

@@ -14,6 +14,20 @@ describe('dateTime', () => {
       })
     ).toBe('Nov 20, 2020');
   });
+
+  it('allows to override a time zone', () => {
+    const formatter = createFormatter({
+      locale: 'en',
+      timeZone: 'Europe/Berlin'
+    });
+    expect(
+      formatter.dateTime(parseISO('2020-11-20T10:36:01.516Z'), {
+        timeStyle: 'medium',
+        dateStyle: 'medium',
+        timeZone: 'America/New_York'
+      })
+    ).toBe('Nov 20, 2020, 5:36:01 AM');
+  });
 });
 
 describe('number', () => {
@@ -284,8 +298,11 @@ describe('dateTimeRange', () => {
           minute: 'numeric'
         }
       )
-    ).toBe('1/10/06, 11:00 AM – 12:00 PM'); // 1 hour more given that the timezone is Europe/Berlin and the date is in UTC
+    )
+      // 1 hour more given that the timezone is Europe/Berlin and the date is in UTC
+      .toBe('1/10/06, 11:00 AM – 12:00 PM');
   });
+
   it('returns a reasonable fallback if an invalid format is provided', () => {
     const formatter = createFormatter({
       locale: 'en',
@@ -299,6 +316,24 @@ describe('dateTimeRange', () => {
       )
     ).toBe('1/10/2007 – 1/10/2008');
   });
+
+  it('allows to override the time zone', () => {
+    const formatter = createFormatter({
+      locale: 'en',
+      timeZone: 'Europe/Berlin'
+    });
+    expect(
+      formatter.dateTimeRange(
+        new Date(2007, 0, 10, 10, 0, 0),
+        new Date(2008, 0, 10, 11, 0, 0),
+        {
+          timeStyle: 'medium',
+          dateStyle: 'medium',
+          timeZone: 'America/New_York'
+        }
+      )
+    ).toBe('Jan 10, 2007, 4:00:00 AM – Jan 10, 2008, 5:00:00 AM');
+  });
 });
 
 describe('list', () => {