glob の使い方 — JavaScriptで最も正確なファイルグロブ実装

一言でいうと

glob は、シェルのワイルドカードパターン（**/*.js など）を使ってファイルシステム上のファイルを検索するNode.jsライブラリです。JavaScript製グロブ実装の中で最も正確で、二番目に高速とされています。

どんな時に使う？

• ビルドツールやCLIツールで、特定のパターンに一致するファイル群を一括取得したい時（例：src/**/*.ts にマッチする全TypeScriptファイル）
• テストランナーやリンターの対象ファイルをパターン指定で動的に収集したい時
• デプロイスクリプトやタスク自動化で、ログファイルや画像ファイルなど特定の拡張子のファイルを再帰的に探索したい時

インストール

# npm
npm install glob

# yarn
yarn add glob

# pnpm
pnpm add glob

注意: パッケージ名は glob です。node-glob は別の放棄されたパッケージなのでご注意ください。

基本的な使い方

import { glob, globSync } from 'glob'

// 非同期: node_modules を除く全 .ts ファイルを取得
const tsFiles: string[] = await glob('**/*.ts', {
  ignore: 'node_modules/**',
})
console.log(tsFiles)

// 同期版
const tsFilesSync: string[] = globSync('**/*.ts', {
  ignore: 'node_modules/**',
})

// 複数パターンを配列で指定
const assets: string[] = await glob([
  'src/**/*.css',
  'src/**/*.{png,jpg,svg}',
])

よく使うAPI

1. glob() — 非同期でファイル一覧を取得

最も基本的なAPI。Promise<string[]> を返します。

import { glob } from 'glob'

const jsFiles = await glob('**/*.js', {
  ignore: 'node_modules/**',
  cwd: './src', // 検索の起点ディレクトリ
})

2. globSync() — 同期版

スクリプトや設定ファイルの読み込みなど、同期処理が許容される場面で使います。

import { globSync } from 'glob'

const configs = globSync('config/*.{json,yaml,yml}')

3. globStream() — ストリームで取得

大量のファイルを扱う場合、メモリ効率の良いストリーム形式で結果を受け取れます。返り値は Minipass ストリームです。

import { globStream } from 'glob'

const stream = globStream('logs/**/*.log')
stream.on('data', (filePath: string) => {
  console.log('found:', filePath)
})
stream.on('end', () => {
  console.log('done')
})

4. Glob クラス — キャッシュを再利用した高速探索

同じディレクトリを複数パターンで探索する場合、Glob クラスを使うとキャッシュが効いて高速になります。async iterable / sync iterable の両方に対応しています。

import { Glob } from 'glob'

// 1つ目のパターンで探索
const g1 = new Glob('**/*.ts', { ignore: 'node_modules/**' })
for await (const file of g1) {
  console.log('ts:', file)
}

// g1 のキャッシュと設定を再利用して別パターンを探索
const g2 = new Glob('**/*.json', g1)
for (const file of g2) {
  console.log('json:', file)
}

5. withFileTypes / stat オプション — ファイル情報付きで取得

withFileTypes: true を指定すると、文字列ではなく Path オブジェクト（fs.Dirent に似た拡張オブジェクト）が返ります。stat: true を併用すると mtime や mode などの情報も取得できます。

import { glob } from 'glob'

const results = await glob('**/*', {
  stat: true,
  withFileTypes: true,
  ignore: 'node_modules/**',
})

// 更新日時でソート
const sortedByMtime = results
  .sort((a, b) => (a.mtimeMs ?? 0) - (b.mtimeMs ?? 0))
  .map(p => p.fullpath())

// ディレクトリのみ抽出
const dirs = results
  .filter(p => p.isDirectory())
  .map(p => p.fullpath())

補足: hasMagic() / escape() / unescape()

パターン文字列のユーティリティ関数も提供されています。

import { hasMagic, escape, unescape } from 'glob'

// パターンにワイルドカードが含まれるか判定
hasMagic('**/*.ts')       // true
hasMagic('src/index.ts')  // false

// 特殊文字をエスケープ（リテラルマッチ用）
escape('file[1].txt')     // 'file\\[1\\].txt'

// エスケープを解除
unescape('file\\[1\\].txt') // 'file[1].txt'

主要オプション一覧

類似パッケージとの比較

速度だけなら fast-glob や fdir が上回るケースがありますが、エッジケースでの正確性やPOSIXグロブ仕様への準拠度では glob が最も信頼できます。

注意点・Tips

グロブパターンのパス区切りは常に / を使う

Windows環境でも、パターン文字列には / を使ってください。\ はグロブのエスケープ文字として解釈されます。

// ❌ Windows でもこれはNG
glob('src\\**\\*.ts')

// ✅ 常にスラッシュを使う
glob('src/**/*.ts')

ignore のオブジェクト形式で高度なフィルタリング

単純な文字列パターンだけでなく、関数ベースで柔軟に除外条件を書けます。childrenIgnored を使うと、ディレクトリ自体の走査をスキップできるためパフォーマンスが向上します。

const results = await glob('**/*', {
  ignore: {
    // .md ファイルを除外
    ignored: (p) => /\.md$/.test(p.name),
    // docs ディレクトリ配下を丸ごとスキップ（走査自体を省略）
    childrenIgnored: (p) => p.isNamed('docs'),
  },
})

AbortSignal でタイムアウトやキャンセルが可能

巨大なファイルツリーを探索する際、タイムアウトを設定しておくと安全です。

const results = await glob('**/*', {
  signal: AbortSignal.timeout(5000), // 5秒でタイムアウト
})

v13 での破壊的変更に注意

glob v13 では CLI が glob-bin パッケージに分離されました。v10/v11 からアップグレードする場合は、CLIを別途インストールする必要があります。また、ESM / CommonJS の両方に対応しています。

バージョン情報: この記事は glob v13.0.6 時点の情報に基づいています。

まとめ

glob は、Node.jsでファイルパターンマッチングを行う際のデファクトスタンダードです。非同期・同期・ストリーム・イテレータと多彩なAPIを備え、withFileTypes や stat オプションによるリッチなファイル情報取得、ignore のオブジェクト形式による柔軟なフィルタリングなど、実用的な機能が充実しています。正確性を重視するプロジェクトでは、まず第一に検討すべきライブラリです。