feat!: Next.js 13 RSC integration

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -29,9 +29,8 @@ body:
       label: Mandatory reproduction URL (CodeSandbox or GitHub repository)
       description: |
         **Templates:**
-        - [CodeSandbox (`app` directory)](https://codesandbox.io/p/sandbox/next-intl-bug-template-forked-yow8ep)
-        - [CodeSandbox (`app` directory, RSC RC)](https://codesandbox.io/p/sandbox/next-intl-bug-template-app-forked-zcymvq)
-        - [CodeSandbox (`pages` directory)](https://codesandbox.io/p/sandbox/next-intl-bug-template-pages-krm37f)
+        - [CodeSandbox (App Router)](https://codesandbox.io/p/sandbox/next-intl-bug-template-app-forked-zcymvq)
+        - [CodeSandbox (Pages Router)](https://codesandbox.io/p/sandbox/next-intl-bug-template-pages-krm37f)
     validations:
       required: true
   - type: textarea

.github/workflows/issue-commenter.yml

@@ -19,9 +19,8 @@ jobs:
             Unfortunately, the reproduction is missing or incomplete, and as such we cannot investigate this issue. Please add a reproduction to the issue, otherwise it will be closed automatically.
 
             **Templates:**
-             - [CodeSandbox (`app` directory)](https://codesandbox.io/p/sandbox/next-intl-bug-template-forked-yow8ep)
-             - [CodeSandbox (`app` directory, RSC RC)](https://codesandbox.io/p/sandbox/next-intl-bug-template-app-forked-zcymvq)
-             - [CodeSandbox (`pages` directory)](https://codesandbox.io/p/sandbox/next-intl-bug-template-pages-krm37f)
+             - [CodeSandbox (App Router)](https://codesandbox.io/p/sandbox/next-intl-bug-template-app-forked-zcymvq)
+             - [CodeSandbox (Pages Router)](https://codesandbox.io/p/sandbox/next-intl-bug-template-pages-krm37f)
 
             **Creating a good bug report takes time.**
 

.github/workflows/main.yml

@@ -20,6 +20,12 @@ jobs:
           cache: 'pnpm'
       - run: pnpm install
 
+      # Next.js caching
+      - uses: actions/cache@v3
+        with:
+          path: ${{ github.workspace }}/examples/*/.next/cache
+          key: ${{ runner.os }}-nextjs-${{ hashFiles('pnpm-lock.yaml') }}
+
       # Playwright
       - run: |
           PLAYWRIGHT_VERSION=$(cat pnpm-lock.yaml | grep /@playwright/test@ | sed 's/.*@\([^:]*\):.*/\1/')
@@ -32,7 +38,7 @@ jobs:
           key: playwright-browsers-${{ env.PLAYWRIGHT_VERSION }}
       - if: steps.cache-playwright-browsers.outputs.cache-hit != 'true'
         # Setting up playwright in one example is sufficient
-        run: pnpm --filter example-next-13 exec playwright install --with-deps
+        run: pnpm --filter example-next-13-advanced exec playwright install --with-deps
 
       - run: pnpm run build
       - run: pnpm run lint

README.md

@@ -51,7 +51,7 @@ export default function UserProfile({user}) {
 }
 ```
 
-```json
+```js
 // en.json
 {
   "UserProfile": {

docs/components/CodeSnippets.tsx

@@ -19,7 +19,7 @@ function icu() {
         <span style={{color: 'var(--shiki-token-punctuation)'}}>:</span>
         <span style={{color: 'var(--shiki-color-text)'}}> </span>
         <span style={{color: 'var(--shiki-token-string-expression)'}}>
-          "{'{'}username{'}'}'s profile"
+          "{'{'}firstName{'}'}'s profile"
         </span>
         <span style={{color: 'var(--shiki-token-punctuation)'}}>,</span>
       </span>

docs/components/Hero.tsx

@@ -47,7 +47,7 @@ export default function Hero({
               </div>
               <Link
                 className="mt-10 inline-flex border border-green-300/50 px-4 py-2 font-semibold text-green-300 transition-colors hover:border-white/50 hover:text-white lg:mt-20"
-                href="/docs"
+                href="/docs/getting-started/app-router"
               >
                 <span className="mr-3 inline-block">📣</span>{' '}
                 <span>{rscAnnouncement}</span>

docs/components/HeroCode.tsx

@@ -195,7 +195,7 @@ const files = [
           <span style={{color: 'var(--shiki-token-punctuation)'}}>:</span>
           <span style={{color: 'var(--shiki-color-text)'}}> </span>
           <span style={{color: 'var(--shiki-token-string-expression)'}}>
-            "{'{'}username{'}'}'s profile"
+            "{'{'}firstname{'}'}'s profile"
           </span>
           <span style={{color: 'var(--shiki-token-punctuation)'}}>,</span>
         </span>

docs/next.config.js

@@ -30,12 +30,17 @@ module.exports = withNextra({
     },
     {
       source: '/docs/getting-started/production-checklist',
-      destination: '/docs/production-checklist',
+      destination: '/docs/environments/runtime-requirements',
       permanent: true
     },
     {
       source: '/docs/usage/production-checklist',
-      destination: '/docs/production-checklist',
+      destination: '/docs/environments/runtime-requirements',
+      permanent: true
+    },
+    {
+      source: '/docs/production-checklist',
+      destination: '/docs/environments/runtime-requirements',
       permanent: true
     },
     {
@@ -45,12 +50,22 @@ module.exports = withNextra({
     },
     {
       source: '/docs/next-13/client-components',
-      destination: '/docs/getting-started/app-router-client-components',
+      destination: '/docs/getting-started/app-router',
       permanent: true
     },
     {
       source: '/docs/next-13/server-components',
-      destination: '/docs/getting-started/app-router-server-components',
+      destination: '/docs/getting-started/app-router',
+      permanent: true
+    },
+    {
+      source: '/docs/getting-started/app-router-server-components',
+      destination: '/docs/getting-started/app-router',
+      permanent: true
+    },
+    {
+      source: '/docs/getting-started/app-router-client-components',
+      destination: '/docs/getting-started/app-router',
       permanent: true
     },
     {
@@ -75,22 +90,17 @@ module.exports = withNextra({
     },
     {
       source: '/docs/usage/production-checklist',
-      destination: '/docs/production-checklist',
+      destination: '/docs/environments/runtime-requirements',
       permanent: true
     },
     {
       source: '/docs/usage/runtime-requirements-polyfills',
-      destination: '/docs/production-checklist#runtime-requirements',
-      permanent: true
-    },
-    {
-      source: '/docs/usage/configuration',
-      destination: '/docs/configuration',
+      destination: '/docs/environments/runtime-requirements',
       permanent: true
     },
     {
       source: '/docs/usage/error-handling',
-      destination: '/docs/configuration#error-handling',
+      destination: '/docs/usage/configuration#error-handling',
       permanent: true
     },
     {

docs/package.json

@@ -24,14 +24,14 @@
     "tailwindcss": "^3.3.2"
   },
   "devDependencies": {
-    "@types/node": "20.1.2",
-    "@types/react": "^18.2.5",
+    "@types/node": "^20.1.2",
+    "@types/react": "^18.2.29",
     "autoprefixer": "^10.4.0",
     "eslint": "^8.46.0",
     "eslint-config-molindo": "^7.0.0",
     "eslint-config-next": "^13.4.0",
     "next-sitemap": "^4.0.7",
-    "typescript": "^5.0.0"
+    "typescript": "^5.2.2"
   },
   "funding": "https://github.com/amannn/next-intl?sponsor=1"
 }

docs/pages/blog/next-intl-3-0.mdx

@@ -108,7 +108,7 @@ Note that if you're using `next-intl` exclusively in Client Components, this doe
 5. `next@^13.4` is now required for the RSC APIs. Next.js 12 is still supported for the Pages Router integration.
 6. If you're using `NextIntlClientProvider` outside of the App Router (e.g. with the Pages Router), you need to define the `locale` prop explicitly.
 7. `useMessages` now has a non-nullable return type for easier consumption and will throw if no messages are configured.
-8. `createTranslator(…).rich` now returns a `ReactNode`. Previously, this was somewhat confusing, since `t.rich` accepted and returned either React elements or strings depending on if you retrieve the fuction via `useTranslations` or `createTranslator`. Now, an explicit [`t.markup`](https://next-intl-docs-git-feat-next-13-rsc-next-intl.vercel.app/docs/usage/messages#html-markup) function has been added to generate markup strings like `'<b>Hello</b>'` outside of React components.
+8. `createTranslator(…).rich` now returns a `ReactNode`. Previously, this was somewhat confusing, since `t.rich` accepted and returned either React elements or strings depending on if you retrieve the fuction via `useTranslations` or `createTranslator`. Now, an explicit [`t.markup`](/docs/usage/messages#html-markup) function has been added to generate markup strings like `'<b>Hello</b>'` outside of React components.
 9. `useIntl` has been replaced with [`useFormatter`](https://next-intl-docs-git-feat-next-13-rsc-next-intl.vercel.app/docs/usage/dates-times) (deprecated since v2.11).
 10. `createIntl` has been replaced with [`createFormatter`](https://next-intl-docs-git-feat-next-13-rsc-next-intl.vercel.app/docs/environments/core-library) (deprecated since v2.11).
 

docs/pages/blog/translations-outside-of-react-components.mdx

@@ -113,26 +113,21 @@ Additionally, this approach is more robust to possibly unexpected states, like t
 
 If you’re working with Next.js, you might want to translate i18n messages in [API routes](https://nextjs.org/docs/pages/building-your-application/routing/api-routes), [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/router-handlers) or the [Metadata API](https://nextjs.org/docs/app/api-reference/file-conventions/metadata).
 
-`next-intl` provides a [core library](/docs/environments/core-library) that is agnostic from React and can be used for these cases.
+`next-intl/server` provides a set of awaitable versions of the functions that you usually call as hooks from within components. These are agnostic from React and can be used for these cases.
 
 ```tsx
-import {createTranslator} from 'next-intl';
+import {getTranslations} from 'next-intl/server';
 
-const messages = {
-  hello: 'Hello {name}!'
-};
+// The `locale` is received from Next.js via `params`
+const locale = params.locale;
 
 // This creates the same function that is returned by `useTranslations`.
-// Since there's no provider, you can pass all the properties you'd
-// usually pass to the provider directly here.
-const t = createTranslator({locale: 'en', messages});
+const t = await getTranslations(locale);
 
 // Result: "Hello world!"
 t('hello', {name: 'world'});
 ```
 
-There's currently a proposal to further simplify this use case, by offering a set of [new APIs that integrate with Server Components](/docs/environments/metadata-route-handlers) (currently in beta).
-
 ## This seems familiar
 
 If you’ve been working with React for a longer time, you might have experienced the change [from `component{DidMount,DidUpdate,WillUnmount}` to `useEffect`](https://legacy.reactjs.org/docs/hooks-effect.html#explanation-why-effects-run-on-each-update). The reason why `useEffect` is superior is because it nudges the developer into a direction where the app is always in sync and by doing this, a whole array of potential issues just magically disappear.

docs/pages/docs/_meta.json

@@ -2,9 +2,7 @@
   "getting-started": "Getting started",
   "usage": "Usage guide",
   "environments": "Environments",
-  "configuration": "Global configuration",
   "routing": "Routing",
   "workflows": "Workflows & integrations",
-  "production-checklist": "Production checklist",
   "faq": "FAQ"
 }

docs/pages/docs/environments/_meta.json

@@ -3,5 +3,6 @@
   "server-client-components": "Server & Client Components",
   "metadata-route-handlers": "Metadata & Route Handlers",
   "error-files": "Error files (e.g. not-found)",
-  "core-library": "Core library"
+  "core-library": "Core library",
+  "runtime-requirements": "Runtime requirements"
 }

docs/pages/docs/environments/core-library.mdx

@@ -18,15 +18,15 @@ const t = createTranslator({locale: 'en', messages});
 // Result: "Hello world!"
 t('basic', {name: 'world'});
 
-// Rich text uses functions that accept and return a string.
-// Result: "Hello <b>world</b>!"
-t.rich('rich', {
+// To generate HTML markup, you can consider using the `markup`
+// function which in contrast to `t.rich` returns a markup string.
+t.markup('rich', {
   name: 'world',
   b: (chunks) => `<b>${chunks}</b>`
 });
 ```
 
-For date, time and number formatting, the `intl` object can be created outside of React as well:
+For date, time and number formatting, the `format` object can be created outside of React as well:
 
 ```js
 import {createFormatter} from 'next-intl';

docs/pages/docs/environments/error-files.mdx

@@ -1,4 +1,3 @@
-import VersionTabs from 'components/VersionTabs';
 import Callout from 'components/Callout';
 
 # Internationalization in Next.js error files
@@ -53,24 +52,19 @@ You can add a root `not-found` page to handle these cases too.
 ```tsx filename="app/not-found.tsx"
 'use client';
 
-import Error from 'next/error';
+import {redirect, usePathname} from 'next/navigation';
 
-// Render the default Next.js 404 page when a route
-// is requested that doesn't match the middleware and
-// therefore doesn't have a locale associated with it.
+const defaultLocale = 'en';
 
 export default function NotFound() {
-  return (
-    <html lang="en">
-      <body>
-        <Error statusCode={404} />
-      </body>
-    </html>
-  );
+  const pathname = usePathname();
+
+  // Add a locale prefix to show a localized not found page
+  redirect(`/${defaultLocale}${pathname}`);
 }
 ```
 
-Note that the presence of `app/not-found.tsx` requires that a root layout is available as well, even if it's just passing `children` through.
+Note that the presence of `app/not-found.tsx` requires that a root layout is available, even if it's just passing `children` through.
 
 ```tsx filename="app/layout.tsx"
 // Since we have a root `not-found.tsx` page, a layout file
@@ -89,12 +83,8 @@ import {notFound} from 'next/navigation';
 const locales = ['en', 'de'];
 
 export default function LocaleLayout({children, params}) {
-  const locale = useLocale();
-
-  // Validate that the incoming `locale` parameter is a valid locale
-  if (params.locale !== locale) {
-    notFound();
-  }
+  // Validate that the incoming `locale` parameter is valid
+  if (!locales.includes(locale as any)) notFound();
 
   return (
     <html lang={locale}>
@@ -125,11 +115,7 @@ When an `error` file is defined, Next.js creates [an error boundary within your
 
 </figure>
 
-Since the `error` file must be defined as a Client Component, you have to use [`NextIntlClientProvider`](/docs/configuration#client-server-components) to provide messages in case the `error` file renders.
-
-If you've [set up `next-intl` to be used in Client Components](/docs/getting-started/app-router-client-components), this is already the case and there's no additional setup needed. If you're using [the Server Components beta](/docs/getting-started/app-router-server-components) though, you have to provide the relevant messages in the wrapping layout.
-
-<figure>
+Since the `error` file must be defined as a Client Component, you have to use [`NextIntlClientProvider`](/docs/usage/configuration#nextintlclientprovider) to provide messages in case the `error` file renders.
 
 ```tsx filename="app/[locale]/layout.tsx"
 import pick from 'lodash/pick';
@@ -153,13 +139,6 @@ export default async function LocaleLayout({children}) {
 }
 ```
 
-<figcaption>
-  Providing messages for the `error` file is only necessary when using [the
-  Server Components beta](/docs/getting-started/app-router-server-components).
-</figcaption>
-
-</figure>
-
 Once `NextIntlClientProvider` is in place, you can use functionality from `next-intl` in the `error` file:
 
 ```tsx filename="app/[locale]/error.tsx"
@@ -178,3 +157,14 @@ export default function Error({error, reset}) {
   );
 }
 ```
+
+Note that `error.tsx` is loaded as soon as the app starts. If your app is performance-senstive and you want to avoid loading translation functionality from `next-intl` as part of the initial bundle, you can export a lazy reference from your `error` file:
+
+```tsx filename="app/[locale]/error.tsx"
+'use client';
+
+import {lazy} from 'react';
+
+// Move error content to a separate chunk and load it only when needed
+export default lazy(() => import('./Error'));
+```

docs/pages/docs/environments/index.mdx

@@ -36,3 +36,5 @@ The `next-intl` APIs are available in the following environments:
     href="/docs/environments/core-library"
   />
 </div>
+
+While modern browsers and server runtimes typically support all necessary JavaScript APIs that are required for `next-intl`, you can double check [the runtime requirements](/docs/environments/runtime-requirements).