Micromatch Glob Matching Utility

Common errors

• npm ERR! code ERESOLVE

  cause Dependency conflict during installation, often due to peer dependency mismatches or incompatible package versions.
  fix Try installing with `--legacy-peer-deps` (`npm install micromatch --legacy-peer-deps`) or `--force` (`npm install micromatch --force`) as a temporary workaround, then investigate the underlying dependency tree to resolve conflicts properly.

• Error: Cannot find module 'micromatch'

  cause The `micromatch` package was not installed or resolved correctly in your project.
  fix Ensure `micromatch` is listed in your `package.json` and run `npm install` or `yarn install`. Verify the package exists in your `node_modules` directory and that your import path is correct (e.g., `import micromatch from 'micromatch';`).

• TypeError: micromatch is not a function (for .isMatch or other methods)

  cause Incorrect import statement when using ESM, or attempting to destructure methods from the default import incorrectly. `micromatch` is the default export, and its utility methods are properties of that default export.
  fix Use `import micromatch from 'micromatch';` and then call methods as `micromatch.isMatch(...)` or `micromatch.not(...)`. Do not attempt `import { isMatch } from 'micromatch';` as these are not named exports.

• Patterns with backslashes behave unexpectedly or don't match correctly.

  cause From v3 onwards, micromatch treats backslashes as escape characters, not path separators. This is a change from v2 behavior.
  fix Always use forward slashes (`/`) as path separators in your glob patterns, even on Windows. If you need to match a literal backslash, you must escape it (e.g., `\\`).

Warnings

• breaking Micromatch v4.x introduced several breaking changes from v3.x, including a minimum Node.js requirement of `>=8.6`. The `micromatch.braces()` method no longer accepts an array of patterns, `strictErrors` was replaced by `strictBrackets=true`, and caching options/methods were removed.
  Fix: Review the official changelog for v4.0.0 and update your glob patterns and options usage accordingly. Ensure your Node.js version meets the minimum requirement.
• breaking Upgrading from micromatch v2.x to v3.x changed how backslashes are handled. Previously, backslashes were converted to forward slashes; now they are respected as escape characters per Bash spec. This can alter matching behavior for existing patterns using backslashes.
  Fix: Use forward slashes (`/`) for path separators in glob patterns instead of backslashes (`\`) to ensure consistent behavior across operating systems and to avoid unintended escape sequences. Escape literal backslashes with another backslash if needed.
• gotcha Micromatch 4.0.8 fixes CVE-2024-4067 and CVE-2024-4068, which are Regular Expression Denial of Service (ReDoS) vulnerabilities in the `micromatch.braces()` function. Maliciously crafted patterns with greedy regex or unclosed brace patterns could lead to catastrophic backtracking, causing severe performance degradation or application unresponsiveness.
  Fix: Upgrade to micromatch `4.0.8` or newer immediately. Implement input validation for user-supplied glob patterns to reject overly complex or malformed inputs. Consider adding timeout mechanisms for pattern matching operations as a defensive measure.
• gotcha Due to parser accuracy improvements in v4, some previously 'invalid' glob patterns that might have worked by coincidence in older versions may now behave differently or fail. This is considered a correction, not a regression.
  Fix: If patterns that previously worked now fail or yield different results, double-check that your glob expressions are syntactically valid according to the Bash 4.3 specification and micromatch's documentation. Adjust patterns to be strictly correct.

Install

• npm install micromatch npm
• yarn add micromatch yarn
• pnpm add micromatch pnpm

Imports

• micromatch
  wrong:

  const micromatch = require('micromatch');

  correct:

  import micromatch from 'micromatch';

  ESM import for modern JavaScript environments. CommonJS `require` is also fully supported, as shown in the package's quickstart.
• micromatch.isMatch
  wrong:

  import { isMatch } from 'micromatch';

  correct:

  import micromatch from 'micromatch';
  micromatch.isMatch('file.js', '*.js');

  isMatch is a property of the default micromatch export, not a named export. Ensure you import the default and access methods via dot notation.
• micromatch (TypeScript types)
  wrong:

  import * as micromatch from 'micromatch'; // While sometimes works, less idiomatic for default exports

  correct:

  import micromatch from 'micromatch';
  // Type definitions are available via @types/micromatch

  For TypeScript projects, install `@types/micromatch` to get full type safety. The library ships with TypeScript support, allowing `import micromatch from 'micromatch';` to work correctly with types.

Quickstart

This quickstart demonstrates basic glob matching, filtering lists of strings, using negation patterns, and performing boolean checks with micromatch. It covers common scenarios like selecting files by extension or excluding specific types, showcasing the flexibility of its API.

import micromatch from 'micromatch';

// Basic usage: filter a list of strings against glob patterns
const files = ['foo.txt', 'bar.js', 'baz.md', 'qux.ts', 'image.png'];
const jsAndMdFiles = micromatch(files, ['*.js', '*.md']);
console.log('Matching .js and .md files:', jsAndMdFiles); // => ['bar.js', 'baz.md']

// Using negation to exclude patterns
const allButJsFiles = micromatch(files, ['*', '!*.js']);
console.log('All files except .js:', allButJsFiles); // => ['foo.txt', 'baz.md', 'qux.ts', 'image.png']

// Boolean matching for a single string
const isSourceFile = micromatch.isMatch('src/index.ts', ['src/**/*.ts', 'src/**/*.tsx']);
console.log('Is src/index.ts a source file?', isSourceFile); // => true

const isConfigFile = micromatch.isMatch('config.json', '**/config.json');
console.log('Is config.json a config file?', isConfigFile); // => true