glob

the most correct and second fastest glob implementation in JavaScript

weekly downloads261.4M

versionv13.0.6

licenseBlueOak-1.0.0

categorytoolchain

Overview

The glob package provides file pattern matching using shell-style wildcards in Node.js applications. It allows developers to select files using patterns like *.js for all JavaScript files or src/**/*.test.ts for test files in nested directories. With over 261 million weekly downloads, it's a fundamental building block in JavaScript tooling ecosystems, powering everything from build systems to test runners.

Created to bring Unix shell glob functionality to JavaScript, glob emphasizes correctness over raw speed—it's deliberately the "most correct" implementation even if not the absolute fastest. It handles edge cases that other implementations miss, including complex brace expansion, character classes, and platform-specific path handling (Windows UNC paths, etc.). The package has evolved through 13 major versions while maintaining a stable, well-tested API.

Glob is maintained as a core infrastructure package used by thousands of other npm packages including webpack, Jest, ESLint, and most major JavaScript tooling. Its design philosophy balances performance with predictability, making it suitable for production environments where correctness cannot be sacrificed. The package supports multiple consumption patterns—promises, synchronous calls, streams, and async iteration—allowing integration into any Node.js codebase architecture.

Developers working with file system operations, build pipelines, CLI tools, or any scenario requiring flexible file selection will find glob essential. It abstracts away the complexity of recursive directory traversal, pattern matching logic, and cross-platform path handling, letting teams focus on business logic rather than reinventing file-finding algorithms.

Quick Start

typescript

import { glob, globSync, globStream } from 'glob';
import { createWriteStream } from 'fs';

// Basic async usage - find all TypeScript files
const tsFiles = await glob('src/**/*.ts', {
  ignore: ['**/*.test.ts', '**/node_modules/**']
});
console.log(`Found ${tsFiles.length} source files`);

// Synchronous with options - find recent log files
const recentLogs = globSync('logs/**/*.log', {
  maxDepth: 3,
  absolute: true,
  stat: true,
  withFileTypes: true
}).filter(entry => {
  const dayOld = Date.now() - (24 * 60 * 60 * 1000);
  return entry.mtime.getTime() > dayOld;
});

// Stream API for memory-efficient processing
const stream = globStream(['images/**/*.{jpg,png}', '!images/thumbnails/**']);
const output = createWriteStream('image-manifest.txt');
for await (const file of stream) {
  output.write(`${file}\n`);
}

// Reusable instance with caching for watch mode
import { Glob } from 'glob';
const watcher = new Glob('src/**/*.js', { ignore: '**/dist/**' });

for await (const file of watcher) {
  console.log('Processing:', file);
  // Subsequent iterations reuse cached directory structure
}

// Multiple patterns with negation
const buildFiles = await glob(['src/**/*', '!**/*.test.*', '!**/__mocks__/**'], {
  nodir: true
});

Use Cases

Build tool file discovery: Bundlers like webpack and Rollup use glob to find entry points and match files for processing. A build script might use glob('src/**/*.{js,ts}') to locate all source files for compilation, or glob('public/**/*.{png,jpg,svg}') to copy static assets.

Test runner file selection: Testing frameworks like Jest and Mocha use glob patterns to discover test files. Developers configure patterns like **/__tests__/**/*.test.js or **/*.spec.ts to automatically locate and execute tests without manual file registration.

Linting and code quality tools: ESLint, Prettier, and similar tools accept glob patterns to specify which files to check. A configuration might use ['src/**/*.js', '!src/**/*.min.js'] to lint all JavaScript except minified files, enabling selective code quality enforcement.

File cleanup and maintenance scripts: DevOps scripts use glob to identify files for deletion or archiving. A cleanup script might use glob('logs/**/*.log', { maxDepth: 2 }) to find log files for rotation, or glob('dist/**/*', { dot: true }) to clear build artifacts including hidden files.

Static site generators: Tools like Eleventy and Gatsby use glob to discover content files. A generator might scan glob('content/**/*.md') for markdown files to convert into HTML pages, supporting flexible content organization without hardcoded file lists.

Pros & Cons

Pros

+Most correct implementation handling edge cases and complex patterns that other libraries miss, crucial for production reliability
+Rich API surface with async promises, synchronous methods, streams, and async iterators supporting diverse application architectures
+Proven stability with 261M weekly downloads and usage in critical infrastructure like webpack, Jest, and ESLint
+Reusable Glob instances with caching optimize repeated operations in the same directory tree, improving performance in watch modes
+Excellent cross-platform support including Windows UNC paths and proper handling of symbolic links and platform-specific quirks

Cons

−Explicitly second-fastest, trading some raw speed for correctness—fast-glob outperforms it in benchmarks for large directory trees
−Adds bundle size overhead compared to zero-dependency solutions or native Node.js fs.glob (available in Node 22.17+)
−Learning curve for advanced features like ignore patterns, custom filesystem implementations, and performance tuning options
−Breaking changes between major versions (currently v13) require migration effort for long-lived projects
−Memory usage can spike with extremely large result sets unless using streaming or async iteration APIs

Alternatives

fast-globv3.3.3

It's a very fast and efficient glob library for Node.js

toolchainglobpatterns

88.5M / week

Comparisons

fast-glob vs glob

toolchain

Install

bash

npm install glob

bash

pnpm add glob

bash

bun add glob

Overview

Quick Start

typescript

import { glob, globSync, globStream } from 'glob';
import { createWriteStream } from 'fs';

// Basic async usage - find all TypeScript files
const tsFiles = await glob('src/**/*.ts', {
  ignore: ['**/*.test.ts', '**/node_modules/**']
});
console.log(`Found ${tsFiles.length} source files`);

// Synchronous with options - find recent log files
const recentLogs = globSync('logs/**/*.log', {
  maxDepth: 3,
  absolute: true,
  stat: true,
  withFileTypes: true
}).filter(entry => {
  const dayOld = Date.now() - (24 * 60 * 60 * 1000);
  return entry.mtime.getTime() > dayOld;
});

// Stream API for memory-efficient processing
const stream = globStream(['images/**/*.{jpg,png}', '!images/thumbnails/**']);
const output = createWriteStream('image-manifest.txt');
for await (const file of stream) {
  output.write(`${file}\n`);
}

// Reusable instance with caching for watch mode
import { Glob } from 'glob';
const watcher = new Glob('src/**/*.js', { ignore: '**/dist/**' });

for await (const file of watcher) {
  console.log('Processing:', file);
  // Subsequent iterations reuse cached directory structure
}

// Multiple patterns with negation
const buildFiles = await glob(['src/**/*', '!**/*.test.*', '!**/__mocks__/**'], {
  nodir: true
});

Use Cases

Pros & Cons

Pros

+Most correct implementation handling edge cases and complex patterns that other libraries miss, crucial for production reliability
+Rich API surface with async promises, synchronous methods, streams, and async iterators supporting diverse application architectures
+Proven stability with 261M weekly downloads and usage in critical infrastructure like webpack, Jest, and ESLint
+Reusable Glob instances with caching optimize repeated operations in the same directory tree, improving performance in watch modes
+Excellent cross-platform support including Windows UNC paths and proper handling of symbolic links and platform-specific quirks

Cons

−Explicitly second-fastest, trading some raw speed for correctness—fast-glob outperforms it in benchmarks for large directory trees
−Adds bundle size overhead compared to zero-dependency solutions or native Node.js fs.glob (available in Node 22.17+)
−Learning curve for advanced features like ignore patterns, custom filesystem implementations, and performance tuning options
−Breaking changes between major versions (currently v13) require migration effort for long-lived projects
−Memory usage can spike with extremely large result sets unless using streaming or async iteration APIs