docs: Storybook (#1266)

Based on #1214

[Draft of new
page](https://next-intl-docs-git-docs-storybook-next-intl.vercel.app/docs/workflows/storybook)

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

@@ -26,7 +26,7 @@ This allows you to use the same APIs that you know from `next-intl` in other env
 2. React Native ([example](/examples#react-native))
 3. Remix ([example](/examples#remix))
 4. Testing environments like Jest ([example](https://github.com/amannn/next-intl/blob/main/examples/example-app-router/src/components/Navigation.spec.tsx))
-5. Storybook (by using a [global decorator](https://storybook.js.org/docs/writing-stories/decorators#global-decorators))
+5. [Storybook](/docs/workflows/storybook)
 
 **Basic usage:**
 

docs/pages/docs/workflows.mdx

@@ -12,5 +12,6 @@ To get the most out of `next-intl`, you can choose from these integrations to im
     href="/docs/workflows/localization-management"
   />
   <Card title="VSCode integration" href="/docs/workflows/vscode-integration" />
-  <Card title="Linting" href="/docs/workflows/linting" />
+  <Card title="ESLint" href="/docs/workflows/linting" />
+  <Card title="Storybook" href="/docs/workflows/storybook" />
 </Cards>

docs/pages/docs/workflows/_meta.json

@@ -2,5 +2,6 @@
   "typescript": "TypeScript",
   "localization-management": "Localization management with Crowdin",
   "vscode-integration": "VSCode integration",
-  "linting": "Linting"
+  "linting": "ESLint",
+  "storybook": "Storybook"
 }

docs/pages/docs/workflows/linting.mdx

@@ -1,4 +1,4 @@
-# Linting
+# ESLint
 
 To ensure correct usage of `next-intl`, you can use ESLint to enforce certain rules.
 

docs/pages/docs/workflows/storybook.mdx

@@ -0,0 +1,27 @@
+import Callout from 'components/Callout';
+import Image from 'next/image';
+
+# Storybook integration for `next-intl`
+
+[Storybook](https://storybook.js.org/) is a tool for developing UI components in isolation.
+
+If you like to set up stories for components that use `next-intl`, you can use [`storybook-next-intl`](https://github.com/stevensacks/storybook-next-intl), a community-maintained addon that configures Storybook accordingly for you.
+
+**Features**
+
+- Sets up [`NextIntlClientProvider`](/docs/usage/configuration#nextintlclientprovider) globally for you
+- Provides a locale switcher so you can test components with different locales
+
+<Image
+  className="mt-6"
+  src="/storybook-integration.png"
+  width={1768}
+  height={1128}
+  alt="Storybook integration for next-intl"
+/>
+
+<Callout>
+
+**Tip:** If you declare components that render as Server Components in your app via non-async functions, these components can render as Client Components in Storybook and will consume configuration from `NextIntlClientProvider` (see also: [Non-async components](/docs/environments/server-client-components#shared-components)).
+
+</Callout>

examples/example-app-router-playground/.eslintrc.js

@@ -5,7 +5,8 @@ module.exports = {
   extends: [
     'molindo/typescript',
     'molindo/react',
-    'plugin:@next/next/recommended'
+    'plugin:@next/next/recommended',
+    'plugin:storybook/recommended'
   ],
   rules: {
     'react/react-in-jsx-scope': 'off'

examples/example-app-router-playground/.gitignore

@@ -2,3 +2,5 @@
 /.next/
 .DS_Store
 tsconfig.tsbuildinfo
+*storybook.log
+storybook-static

examples/example-app-router-playground/.storybook/main.ts

@@ -0,0 +1,12 @@
+import type {StorybookConfig} from '@storybook/nextjs';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.tsx'],
+  addons: ['storybook-next-intl'],
+  framework: {
+    name: '@storybook/nextjs',
+    options: {}
+  },
+  staticDirs: ['../public']
+};
+export default config;

examples/example-app-router-playground/.storybook/next-intl.ts

@@ -0,0 +1,13 @@
+import en from '../messages/en.json';
+import de from '../messages/de.json';
+import es from '../messages/es.json';
+import ja from '../messages/ja.json';
+
+const messagesByLocale: Record<string, any> = {en, de, es, ja};
+
+const nextIntl = {
+  defaultLocale: 'en',
+  messagesByLocale
+};
+
+export default nextIntl;

examples/example-app-router-playground/.storybook/preview.ts

@@ -0,0 +1,19 @@
+import type {Preview} from '@storybook/react';
+import nextIntl from './next-intl';
+
+const preview: Preview = {
+  initialGlobals: {
+    locale: 'en',
+    locales: {
+      en: 'English',
+      de: 'Deutsch',
+      es: 'Español',
+      ja: '日本語'
+    }
+  },
+  parameters: {
+    nextIntl
+  }
+};
+
+export default preview;

examples/example-app-router-playground/package.json

@@ -10,7 +10,8 @@
     "test:playwright:trailing-slash": "TRAILING_SLASH=true pnpm build && TEST_MATCH=trailing-slash.spec.ts playwright test",
     "test:jest": "jest",
     "build": "next build",
-    "start": "next start"
+    "start": "next start",
+    "storybook": "storybook dev -p 6006"
   },
   "dependencies": {
     "@mdx-js/react": "^3.0.1",
@@ -27,6 +28,8 @@
     "@mdx-js/loader": "^3.0.1",
     "@next/mdx": "^14.2.5",
     "@playwright/test": "^1.44.1",
+    "@storybook/nextjs": "^8.2.9",
+    "@storybook/react": "^8.2.9",
     "@testing-library/react": "^16.0.0",
     "@types/jest": "^29.5.12",
     "@types/lodash": "^4.17.5",
@@ -35,12 +38,16 @@
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "chokidar-cli": "3.0.0",
+    "css-loader": "^6.8.1",
     "eslint": "^8.56.0",
     "eslint-config-molindo": "^7.0.0",
     "eslint-config-next": "^14.2.4",
+    "eslint-plugin-storybook": "^0.8.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "sharp": "^0.33.4",
+    "storybook": "^8.2.9",
+    "storybook-next-intl": "^1.1.4",
     "typescript": "^5.5.3"
   }
 }

examples/example-app-router-playground/src/components/Navigation.stories.tsx

@@ -0,0 +1,11 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import Navigation from './Navigation';
+
+const meta = {
+  title: 'components/Navigation',
+  component: Navigation
+} satisfies Meta<typeof Navigation>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};