{"id":10954,"library":"glob","title":"Glob File Matching Utility","description":"The `glob` package provides a robust and highly performant implementation for matching files using shell-like patterns in JavaScript. It is widely considered one of the most correct and fastest glob implementations available, supporting standard glob features such as wildcards, brace expansion, and extended globs. The current stable version is 13.0.6, and it targets modern Node.js environments (v18, v20, >=v22). The library emphasizes correctness according to shell standards and offers both synchronous and asynchronous APIs, including stream-based operations and an advanced `Glob` object for optimized, re-usable pattern matching. A key differentiator is its `withFileTypes` option, which returns enhanced `Path` objects (similar to `fs.Dirent`) for rich file metadata access and manipulation, including custom sorting and filtering based on file stats. It is actively maintained with a regular release cadence for bug fixes and feature enhancements.","status":"active","version":"13.0.6","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/isaacs/node-glob","tags":["javascript","typescript"],"install":[{"cmd":"npm install glob","lang":"bash","label":"npm"},{"cmd":"yarn add glob","lang":"bash","label":"yarn"},{"cmd":"pnpm add glob","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for path manipulation and directory traversal, especially when `withFileTypes` is enabled, providing enhanced `Path` objects.","package":"path-scurry","optional":false}],"imports":[{"note":"Primary asynchronous function for matching files, returns a Promise<string[]>. Named export, not default. CommonJS requires destructuring.","wrong":"const glob = require('glob').glob","symbol":"glob","correct":"import { glob } from 'glob'"},{"note":"Class for creating reusable glob instances, useful for multiple walks or iterating. This is a named export, not a default import. CommonJS requires destructuring.","wrong":"import Glob from 'glob'","symbol":"Glob","correct":"import { Glob } from 'glob'"},{"note":"Synchronous version of `glob`, returns `string[]`. Similar to `glob`, it's a named export and requires destructuring for CommonJS.","wrong":"require('glob').globSync()","symbol":"globSync","correct":"import { globSync } from 'glob'"}],"quickstart":{"code":"import { glob, Glob } from 'glob';\nimport { AbortSignal } from 'node:os'; // Or 'node-abort-controller' for older Node.js\n\nasync function runGlobExamples() {\n  // Find all JavaScript files, ignoring node_modules\n  console.log('Finding JS files (excluding node_modules)...');\n  const jsFiles = await glob('**/*.js', { ignore: 'node_modules/**' });\n  console.log('Found JS files:', jsFiles.slice(0, 5), '...');\n\n  // Find images with multiple patterns\n  console.log('\\nFinding image files...');\n  const images = await glob(['css/*.{png,jpeg}', 'public/*.{png,jpeg}']);\n  console.log('Found images:', images);\n\n  // Using a Glob object for reusability and async iteration\n  console.log('\\nIterating with Glob object for \"**/foo\"...');\n  const g = new Glob('**/foo', {});\n  let fooCount = 0;\n  for await (const file of g) {\n    console.log('Found foo file:', file);\n    fooCount++;\n    if (fooCount > 3) break; // Limit output for example\n  }\n  if (fooCount === 0) console.log('No foo files found in this example.');\n\n  // Find files with detailed file types and stats, sorted by modification time\n  console.log('\\nFinding all files with stats, sorted by mtime...');\n  const results = await glob('**', { stat: true, withFileTypes: true, nodir: true });\n  const timeSortedFiles = results\n    .sort((a, b) => a.mtimeMs - b.mtimeMs)\n    .map(path => ({ path: path.fullpath(), mtime: new Date(path.mtimeMs).toLocaleTimeString() }))\n    .slice(0, 5);\n  console.log('Top 5 recently modified files:', timeSortedFiles);\n}\n\nrunGlobExamples().catch(console.error);","lang":"typescript","description":"Demonstrates asynchronous glob matching, multi-pattern support, iteration with the `Glob` class, and retrieving detailed file type information with stats."},"warnings":[{"fix":"Always use `npm install glob` and `import { ... } from 'glob'` or `require('glob')`.","message":"The npm package name is `glob`, not `node-glob`. The `node-glob` package is a different, abandoned project. Installing or referencing `node-glob` will lead to using an outdated and unmaintained library.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the `glob` v13 documentation for current API signatures and return types. Migrate to named exports for all functions (`glob`, `globSync`, `globStream`, etc.) and the `Glob` class.","message":"Previous major versions might have used different argument signatures or returned different types. For instance, `glob.sync` might have been a direct property on the main `glob` export in older versions, which is not the case in v13.","severity":"breaking","affected_versions":"<13.0.0"},{"fix":"Wrap `await glob(...)` calls in an `async` function or ensure your environment supports top-level `await`.","message":"When using `async`/`await` with `glob` (the default asynchronous function), ensure your code is within an `async` function or top-level `await` is enabled, otherwise, you'll receive a `Promise` instead of the resolved file list.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Review the documentation for the `ignore` option. For simple patterns, use string/array. For advanced filtering, ensure your `ignored` and `childrenIgnored` functions are efficient and correctly handle `Path` objects if `withFileTypes` is used.","message":"The `ignore` option can accept a string, an array of strings, or an object with `ignored` and/or `childrenIgnored` functions for custom ignore logic. Misunderstanding this flexibility can lead to files not being ignored as expected or performance issues with complex custom ignore functions.","severity":"gotcha","affected_versions":">=10.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const { glob } = require('glob');` then call `glob(...)`. For ESM, use `import { glob } from 'glob';`.","cause":"Attempting to call `require('glob')()` directly or incorrect destructuring in CommonJS.","error":"TypeError: glob is not a function"},{"fix":"Define an `async` function and call `glob` inside it, or enable top-level await in your Node.js environment (requires Node.js 14+ and ESM modules).","cause":"Using `await glob(...)` outside an `async` function or a module with top-level await enabled.","error":"SyntaxError: await is only valid in async functions and the top level bodies of modules"},{"fix":"Increase your system's file descriptor limit (e.g., `ulimit -n 4096` on Unix-like systems) or use `globStream` for memory efficiency and to avoid opening too many files simultaneously.","cause":"Globbing a very large number of files on systems with low file descriptor limits, especially with `stat: true`.","error":"Error: EMFILE: too many open files, open '...'"}],"ecosystem":"npm"}