fix(useExtracted): Filter common directories from srcPath, if not explicitly requested (#2093)

Ignore `node_modules`, `.next` and `.git` by default, allowing consumers
to use `srcPath: './'` in case they're not using a `src` directory. In a
future iteration, we might infer these directories from `.gitignore`.

Note that you can still use:

```
srcPath: ['./src', './node_modules/@acme/components'],
```

… in case you want to extract from source files inside of such a
directory.

This PR also contains a fix that allows using trailing slashes in
`srcPath` (e.g. `./src/app/`).

---------

Co-authored-by: Cursor Agent <[email protected]>

Author: amannn

docs/src/pages/docs/usage/plugin.mdx

@@ -128,7 +128,7 @@ If your project is split into multiple folders, you can provide an array of path
 
 ```tsx
 // Not using a `src` folder
-srcPath: ['./app', './components'],
+srcPath: './',
 ```
 
 ```tsx
@@ -141,6 +141,8 @@ srcPath: ['./src', '../ui'],
 srcPath: ['./src', './node_modules/@acme/components'],
 ```
 
+Note that the directories `node_modules`, `.next` and `.git` are automatically excluded from extraction, except for if they appear explicitly in the `srcPath` array.
+
 If you want to provide messages along with your package, you can also extract them [manually](/docs/usage/extraction#manual).
 
 **Note:** The `srcPath` option should be used together with [`extract`](#extract) and [`messages`](#messages).

packages/next-intl/src/extractor/ExtractionCompiler.test.tsx

@@ -7,6 +7,9 @@ const filesystem: {
   project: {
     src: Record<string, string>;
     messages: Record<string, string> | undefined;
+    node_modules?: Record<'@acme', Record<'ui', Record<string, string>>>;
+    '.next'?: Record<string, Record<string, string>>;
+    '.git'?: Record<string, Record<string, string>>;
   };
 } = {
   project: {
@@ -15,16 +18,19 @@ const filesystem: {
   }
 };
 
-describe('json format', () => {
-  beforeEach(() => {
-    filesystem.project.src = {};
-    filesystem.project.messages = {};
-    fileTimestamps.clear();
-    watchCallbacks.clear();
-    mockWatchers.clear();
-    vi.clearAllMocks();
-  });
+beforeEach(() => {
+  filesystem.project = {
+    src: {},
+    messages: {}
+  };
+  delete (filesystem as Record<string, unknown>).ui;
+  fileTimestamps.clear();
+  watchCallbacks.clear();
+  mockWatchers.clear();
+  vi.clearAllMocks();
+});
 
+describe('json format', () => {
   function createCompiler() {
     return new ExtractionCompiler(
       {
@@ -310,28 +316,28 @@ describe('json format', () => {
       `
     );
     expect(filesystem).toMatchInlineSnapshot(`
-    {
-      "project": {
-        "messages": {
-          "de.json": "{
-      "+YJVTi": "Hallo!"
-    }",
-          "en.json": "{
-      "+YJVTi": "Hey!"
-    }",
-        },
-        "src": {
-          "Greeting.tsx": "
-        import {useExtracted} from 'next-intl';
-        function Greeting() {
-          const t = useExtracted();
-          return <div>{t('Hey!')}</div>;
-        }
-        ",
+      {
+        "project": {
+          "messages": {
+            "de.json": "{
+        "+YJVTi": "Hallo!"
+      }",
+            "en.json": "{
+        "+YJVTi": "Hey!"
+      }",
+          },
+          "src": {
+            "Greeting.tsx": "
+          import {useExtracted} from 'next-intl';
+          function Greeting() {
+            const t = useExtracted();
+            return <div>{t('Hey!')}</div>;
+          }
+          ",
+          },
         },
-      },
-    }
-  `);
+      }
+    `);
 
     simulateManualFileEdit(
       'messages/de.json',
@@ -692,15 +698,6 @@ describe('json format', () => {
 });
 
 describe('po format', () => {
-  beforeEach(() => {
-    filesystem.project.src = {};
-    filesystem.project.messages = {};
-    fileTimestamps.clear();
-    watchCallbacks.clear();
-    mockWatchers.clear();
-    vi.clearAllMocks();
-  });
-
   function createCompiler() {
     return new ExtractionCompiler(
       {
@@ -1229,6 +1226,106 @@ msgstr "Hallo!"
   });
 });
 
+describe('`srcPath` filtering', () => {
+  beforeEach(() => {
+    filesystem.project.src['Greeting.tsx'] = `
+    import {useExtracted} from 'next-intl';
+    import Panel from '@acme/ui/panel';
+    function Greeting() {
+      const t = useExtracted();
+      return <Panel>{t('Hey!')}</Panel>;
+    }
+    `;
+
+    function createNodeModule(moduleName: string) {
+      return `
+      import {useExtracted} from 'next-intl';
+      export default function Module({children}) {
+        const t = useExtracted();
+        return (
+          <div>
+            <h1>{t('${moduleName}')}</h1>
+            {children}
+          </div>
+        )
+      }
+      `;
+    }
+
+    filesystem.project.node_modules = {
+      '@acme': {
+        ui: {
+          'panel.tsx': createNodeModule('panel.source')
+        }
+      }
+    };
+    filesystem.project['.next'] = {
+      build: {
+        'panel.tsx': createNodeModule('panel.compiled')
+      }
+    };
+    filesystem.project['.git'] = {
+      config: {
+        'panel.tsx': createNodeModule('panel.config')
+      }
+    };
+  });
+
+  function createCompiler(srcPath: string | Array<string>) {
+    return new ExtractionCompiler(
+      {
+        srcPath,
+        sourceLocale: 'en',
+        messages: {
+          path: './messages',
+          format: 'json',
+          locales: 'infer'
+        }
+      },
+      {isDevelopment: true, projectRoot: '/project'}
+    );
+  }
+
+  it('skips node_modules, .next and .git by default', async () => {
+    using compiler = createCompiler('./');
+    await compiler.compile(
+      '/project/src/Greeting.tsx',
+      filesystem.project.src['Greeting.tsx']
+    );
+    await waitForWriteFileCalls(1);
+    expect(vi.mocked(fs.writeFile).mock.calls).toMatchInlineSnapshot(`
+      [
+        [
+          "messages/en.json",
+          "{
+        "+YJVTi": "Hey!"
+      }",
+        ],
+      ]
+    `);
+  });
+
+  it('includes node_modules if explicitly requested', async () => {
+    using compiler = createCompiler(['./', './node_modules/@acme/ui']);
+    await compiler.compile(
+      '/project/src/Greeting.tsx',
+      filesystem.project.src['Greeting.tsx']
+    );
+    await waitForWriteFileCalls(1);
+    expect(vi.mocked(fs.writeFile).mock.calls).toMatchInlineSnapshot(`
+      [
+        [
+          "messages/en.json",
+          "{
+        "JwjlWH": "panel.source",
+        "+YJVTi": "Hey!"
+      }",
+        ],
+      ]
+    `);
+  });
+});
+
 /**
  * Test utils
  ****************************************************************/

packages/next-intl/src/extractor/source/SourceFileFilter.tsx

@@ -1,10 +1,46 @@
 import path from 'path';
 
 export default class SourceFileFilter {
-  static readonly EXTENSIONS = ['ts', 'tsx', 'js', 'jsx'];
+  public static readonly EXTENSIONS = ['ts', 'tsx', 'js', 'jsx'];
+
+  // Will not be entered, except if explicitly asked for
+  // TODO: At some point we should infer these from .gitignore
+  private static readonly IGNORED_DIRECTORIES = [
+    'node_modules',
+    '.next',
+    '.git'
+  ];
 
   static isSourceFile(filePath: string) {
     const ext = path.extname(filePath);
     return SourceFileFilter.EXTENSIONS.map((cur) => '.' + cur).includes(ext);
   }
+
+  static shouldEnterDirectory(
+    dirPath: string,
+    srcPaths: Array<string>
+  ): boolean {
+    const dirName = path.basename(dirPath);
+    if (SourceFileFilter.IGNORED_DIRECTORIES.includes(dirName)) {
+      return SourceFileFilter.isIgnoredDirectoryExplicitlyIncluded(
+        dirPath,
+        srcPaths
+      );
+    }
+    return true;
+  }
+
+  private static isIgnoredDirectoryExplicitlyIncluded(
+    ignoredDirPath: string,
+    srcPaths: Array<string>
+  ): boolean {
+    return srcPaths.some((srcPath) =>
+      SourceFileFilter.isWithinPath(srcPath, ignoredDirPath)
+    );
+  }
+
+  private static isWithinPath(targetPath: string, basePath: string): boolean {
+    const relativePath = path.relative(basePath, targetPath);
+    return relativePath === '' || !relativePath.startsWith('..');
+  }
 }

packages/next-intl/src/extractor/source/SourceFileScanner.tsx

@@ -12,6 +12,9 @@ export default class SourceFileScanner {
     for (const entry of entries) {
       const entryPath = path.join(dir, entry.name);
       if (entry.isDirectory()) {
+        if (!SourceFileFilter.shouldEnterDirectory(entryPath, srcPaths)) {
+          continue;
+        }
         await SourceFileScanner.walkSourceFiles(entryPath, srcPaths, acc);
       } else {
         if (SourceFileFilter.isSourceFile(entry.name)) {

packages/next-intl/src/plugin/getNextConfig.tsx

@@ -148,15 +148,19 @@ export default function getNextConfig(
         throwError('Message extraction requires Next.js 16 or higher.');
       }
       rules ??= getTurboRules();
+      const srcPaths = (
+        Array.isArray(pluginConfig.experimental.srcPath!)
+          ? pluginConfig.experimental.srcPath!
+          : [pluginConfig.experimental.srcPath!]
+      ).map((srcPath) =>
+        srcPath.endsWith('/') ? srcPath.slice(0, -1) : srcPath
+      );
       addTurboRule(rules!, `*.{${SourceFileFilter.EXTENSIONS.join(',')}}`, {
         loaders: [getExtractMessagesLoaderConfig()],
         condition: {
           // Note: We don't need `not: 'foreign'`, because this is
           // implied by the filter based on `srcPath`.
-          path:
-            (Array.isArray(pluginConfig.experimental.srcPath)
-              ? `{${pluginConfig.experimental.srcPath.join(',')}}`
-              : pluginConfig.experimental.srcPath) + '/**/*',
+          path: `{${srcPaths.join(',')}}` + '/**/*',
           content: /(useExtracted|getExtracted)/
         }
       });