Picomatch

A blazing fast, zero-dependency JavaScript glob pattern matching library, supporting standard and extended Bash glob features.

Trigger Scenarios

Use when the user needs file path matching, glob wildcards (*, **, ?, [...]), .gitignore-style exclusion rules, build tool file filtering, CLI path filtering, file watcher allow/deny lists, etc. Trigger keywords: picomatch, glob matching, .js, **/.ts, wildcards, .gitignore pattern matching, file filtering, minimatch alternative.

Installation

npm install picomatch

Core API

picomatch(glob[, options]) → matcher

Main entry point: Takes a glob pattern and returns a matcher function.

const pm = require('picomatch');
const isMatch = pm('*.js');

isMatch('a.js');  // true
isMatch('a.md');  // false
isMatch('a/b.js'); // false (* does not cross /)

picomatch.isMatch(string, patterns[, options])

Directly checks if a string matches any pattern, without manually calling a matcher.

picomatch.isMatch('a.a', ['b.*', '*.a']); // true
picomatch.isMatch('a.a', 'b.*');          // false

picomatch.matchBase(input, glob)

Matches only the basename of a path (ignores directories).

picomatch.matchBase('foo/bar.js', '*.js');  // true

picomatch.scan(input[, options])

Parses a glob pattern into a structured object.

picomatch.scan('!./foo/*.js', { tokens: true });
// { prefix: '!./', base: 'foo', glob: '*.js', negated: true, tokens: [...] }

picomatch.parse(pattern[, options]) → state

Converts a glob to an intermediate state object, which can be used with .compileRe / .makeRe.

picomatch.makeRe(pattern[, options]) → RegExp

Directly converts a glob to a RegExp.

picomatch.makeRe('*.js');  // /^(?:(?!\.)(?=.)[^/]*?\.js)$/

picomatch.toRegex(source[, options]) → RegExp

Creates a RegExp from a regex source string.

Common Options

Glob Syntax Quick Reference

Practical Pattern Examples

const pm = require('picomatch');

// JS/TS files
pm('**/*.{js,ts,mjs}');

// Ignore node_modules
pm('**', { ignore: 'node_modules/**' });

// Specific extension with subdirectories
pm('src/**/*.md');

// Dotfiles (hidden files)
pm('.*', { dot: true });

// Case-insensitive (Windows/macOS)
pm('*.JPG', { nocase: true });

// Windows paths
pm('src\\**\\*.js', { windows: true });

Common Use Cases

• File watcher allow/deny lists — glob filtering for watchman / chokidar
• .gitignore parsing — parsing ignore pattern lists
• CLI path filtering — underlying engine for glob / fast-glob
• Build artifact matching — determining if a file belongs to dist output
• minimatch alternative — similar API but better performance (micromatch ecosystem)

Detailed Reference

For complete API signatures, option descriptions, scan options, and option examples, see references/api_reference.md.