feat: Revamp extraction/tree shaking pipeline

.github/workflows/main.yml

@@ -20,7 +20,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 24.x
           cache: "pnpm"
       - run: pnpm install
 

.github/workflows/prerelease-canary.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           cache: "pnpm"
-          node-version: 20.x
+          node-version: 24.x
           registry-url: "https://registry.npmjs.org"
       - run: pnpm install
       - run: pnpm turbo run build --filter './packages/**'

.github/workflows/release.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           cache: "pnpm"
-          node-version: 20.x
+          node-version: 24.x
           registry-url: "https://registry.npmjs.org"
       - run: npm install -g npm@latest # Trusted publishers
       - run: pnpm install

AGENTS.md

@@ -1,14 +1,21 @@
 # Agents
 
-## Always
+## Conventions
+
+- Don't use single-character variable names, use descriptive names but keep them as short as possible.
+
+## Workflows
+
+### Always
 
 - If running a test with vitest, use "run" to avoid being stuck in watch mode.
+- When making a change to something in `./packages` and you want to test the updated behavior in consuming apps, you need to build the packages first (`pnpm -w build-packages`)
 
-## When committing
+### When committing
 
 - Make sure ESLint and Prettier pass on changed files.
 - Make sure all tests pass.
 
-## When creating a PR
+### When creating a PR
 
 - When creating a PR, use conventional commit prefixes for the PR title (e.g. `fix: `, `feat: `, ...).

e2e/extracted-custom/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.next/
+playwright-report/
+test-results/

e2e/extracted-custom/POCodecSourceMessageKey.ts

@@ -0,0 +1,151 @@
+import POParser from 'po-parser';
+import type {Entry} from 'po-parser';
+import {defineCodec} from 'next-intl/extractor';
+
+type ExtractedMessage = {
+  id: string;
+  message: string;
+  description?: string;
+  references?: Entry['references'];
+  /** Allows for additional properties like .po flags to be read and later written. */
+  [key: string]: unknown;
+};
+
+export default defineCodec(() => {
+  const DEFAULT_METADATA = {
+    'Content-Type': 'text/plain; charset=utf-8',
+    'Content-Transfer-Encoding': '8bit',
+    'X-Generator': 'next-intl'
+  };
+
+  const metadataByLocale = new Map();
+
+  return {
+    decode(content, context) {
+      const catalog = POParser.parse(content);
+      if (catalog.meta) {
+        metadataByLocale.set(context.locale, catalog.meta);
+      }
+      const messages =
+        catalog.messages || ([] as NonNullable<typeof catalog.messages>);
+
+      return messages.map((msg) => {
+        const {extractedComments, msgctxt, msgid, msgstr, ...rest} = msg;
+
+        // Necessary to restore the ID
+        if (!msgctxt) {
+          throw new Error('msgctxt is required');
+        }
+
+        if (extractedComments && extractedComments.length > 1) {
+          throw new Error(
+            `Multiple extracted comments are not supported. Found ${extractedComments.length} comments for msgid "${msgid}".`
+          );
+        }
+
+        return {
+          ...rest,
+          id: msgctxt,
+          message: msgstr,
+          ...(extractedComments &&
+            extractedComments.length > 0 && {
+              description: extractedComments[0]
+            })
+        };
+      });
+    },
+
+    encode(messages, context) {
+      const encodedMessages = getSortedMessages(messages).map((msg) => {
+        const sourceMessage = context.sourceMessagesById.get(msg.id)?.message;
+        if (!sourceMessage) {
+          throw new Error(
+            `Source message not found for id "${msg.id}" in locale "${context.locale}".`
+          );
+        }
+
+        // Store the hashed ID in msgctxt so we can restore it during decode
+        const {description, id, message, ...rest} = msg;
+        return {
+          ...(description && {extractedComments: [description]}),
+          ...rest,
+          msgctxt: id,
+          msgid: sourceMessage,
+          msgstr: message
+        };
+      });
+
+      return POParser.serialize({
+        meta: {
+          Language: context.locale,
+          ...DEFAULT_METADATA,
+          ...metadataByLocale.get(context.locale)
+        },
+        messages: encodedMessages
+      });
+    },
+
+    toJSONString(source, context) {
+      const parsed = this.decode(source, context);
+      const messagesObject = {};
+      for (const message of parsed) {
+        setNestedProperty(messagesObject, message.id, message.message);
+      }
+      return JSON.stringify(messagesObject);
+    }
+  };
+});
+
+// Essentialls lodash/set, but we avoid this dependency
+function setNestedProperty(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  obj: Record<string, any>,
+  keyPath: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  value: any
+): void {
+  const keys = keyPath.split('.');
+  let current = obj;
+
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (
+      !(key in current) ||
+      typeof current[key] !== 'object' ||
+      current[key] === null
+    ) {
+      current[key] = {};
+    }
+    current = current[key];
+  }
+
+  current[keys[keys.length - 1]] = value;
+}
+
+function getSortedMessages(
+  messages: Array<ExtractedMessage>
+): Array<ExtractedMessage> {
+  return messages.toSorted((messageA, messageB) => {
+    const refA = messageA.references?.[0];
+    const refB = messageB.references?.[0];
+
+    // No references: preserve original (extraction) order
+    if (!refA || !refB) return 0;
+
+    // Sort by path, then line. Same path+line: preserve original order
+    return compareReferences(refA, refB);
+  });
+}
+
+function compareReferences(
+  refA: NonNullable<Entry['references']>[number],
+  refB: NonNullable<Entry['references']>[number]
+): number {
+  const pathCompare = localeCompare(refA.path, refB.path);
+  if (pathCompare !== 0) return pathCompare;
+  return (refA.line ?? 0) - (refB.line ?? 0);
+}
+
+function localeCompare(a: string, b: string) {
+  return a.localeCompare(b, 'en');
+}

e2e/extracted-custom/eslint.config.mjs

@@ -0,0 +1,20 @@
+import {defineConfig} from 'eslint/config';
+import nextVitals from 'eslint-config-next/core-web-vitals';
+import nextTs from 'eslint-config-next/typescript';
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  {
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+          varsIgnorePattern: '^_'
+        }
+      ]
+    }
+  }
+]);

e2e/extracted-custom/messages/de.po

@@ -0,0 +1,17 @@
+msgid ""
+msgstr ""
+"Language: de\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"X-Generator: next-intl\n"
+
+#: src/app/page.tsx:9
+msgctxt "NhX4DJ"
+msgid "Hello"
+msgstr "Hallo"
+
+#: src/components/Footer.tsx:7
+#: src/components/Greeting.tsx:7
+msgctxt "+YJVTi"
+msgid "Hey!"
+msgstr ""

e2e/extracted-custom/messages/en.po

@@ -0,0 +1,17 @@
+msgid ""
+msgstr ""
+"Language: en\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"X-Generator: next-intl\n"
+
+#: src/app/page.tsx:9
+msgctxt "NhX4DJ"
+msgid "Hello"
+msgstr "Hello"
+
+#: src/components/Footer.tsx:7
+#: src/components/Greeting.tsx:7
+msgctxt "+YJVTi"
+msgid "Hey!"
+msgstr "Hey!"

e2e/extracted-custom/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

e2e/extracted-custom/next.config.ts

@@ -0,0 +1,20 @@
+import {NextConfig} from 'next';
+import createNextIntlPlugin from 'next-intl/plugin';
+
+const withNextIntl = createNextIntlPlugin({
+  experimental: {
+    srcPath: './src',
+    extract: {sourceLocale: 'en'},
+    messages: {
+      path: './messages',
+      format: {
+        codec: './POCodecSourceMessageKey.ts',
+        extension: '.po'
+      },
+      locales: 'infer'
+    }
+  }
+});
+
+const config: NextConfig = {};
+export default withNextIntl(config);

e2e/extracted-custom/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "e2e-extracted-custom",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "lint": "eslint src && prettier src --check",
+    "build": "next build",
+    "start": "next start",
+    "test": "playwright test"
+  },
+  "dependencies": {
+    "next": "^16.0.10",
+    "next-intl": "workspace:*",
+    "po-parser": "^2.1.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "shared-ui": "workspace:*"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.1.0",
+    "@playwright/test": "^1.51.1",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^9.38.0",
+    "eslint-config-next": "^16.0.10",
+    "prettier": "^3.3.3",
+    "typescript": "^5.5.3"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "bracketSpacing": false,
+    "trailingComma": "none"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

e2e/extracted-custom/playwright.config.ts

@@ -0,0 +1,18 @@
+import {defineConfig, devices} from '@playwright/test';
+
+const PORT = process.env.CI ? 3023 : 3022;
+
+export default defineConfig({
+  fullyParallel: false,
+  testDir: './tests',
+  timeout: 120_000,
+  use: {
+    ...devices['Desktop Chrome'],
+    baseURL: `http://localhost:${PORT}`
+  },
+  webServer: {
+    command: `PORT=${PORT} pnpm dev`,
+    port: PORT,
+    reuseExistingServer: true
+  }
+});

e2e/extracted-custom/src/app/layout.tsx

@@ -0,0 +1,14 @@
+import {NextIntlClientProvider} from 'next-intl';
+import {getLocale} from 'next-intl/server';
+
+export default async function RootLayout({children}: LayoutProps<'/'>) {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale}>
+      <body>
+        <NextIntlClientProvider>{children}</NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}

e2e/extracted-custom/src/app/page.tsx

@@ -0,0 +1,14 @@
+import {useExtracted} from 'next-intl';
+import Greeting from '@/components/Greeting';
+import Footer from '@/components/Footer';
+
+export default function Page() {
+  const t = useExtracted();
+  return (
+    <div>
+      <h1>{t('Hello')}</h1>
+      <Greeting />
+      <Footer />
+    </div>
+  );
+}

e2e/extracted-custom/src/components/Footer.tsx

@@ -0,0 +1,8 @@
+'use client';
+
+import {useExtracted} from 'next-intl';
+
+export default function Footer() {
+  const t = useExtracted();
+  return <footer>{t('Hey!')}</footer>;
+}

e2e/extracted-custom/src/components/Greeting.tsx

@@ -0,0 +1,8 @@
+'use client';
+
+import {useExtracted} from 'next-intl';
+
+export default function Greeting() {
+  const t = useExtracted();
+  return <div>{t('Hey!')}</div>;
+}