Incremental Compiler

21.0.45 verified Fri May 01 auth: no javascript

A library for building incremental compilers and file watchers in Node.js, version 21.0.45. It wraps @parcel/watcher and chokidar to provide a unified, event-driven API for watching file changes and triggering compilation. Supports TypeScript, project-based configuration, and automatically ignores node_modules and .git. Unlike raw chokidar, it abstracts away watcher differences and provides a base class for project-aware compilation.

Common errors

error Cannot find module 'incremental-compiler' ↓

cause Importing from package root instead of 'incremental-compiler/src'.

fix

Change import to 'incremental-compiler/src'.

error TypeError: incrementalWatcher is not a function ↓

cause Incorrect import path or missing destructuring.

fix

Ensure you import as: import { incrementalWatcher } from 'incremental-compiler/src'.

error Error: options must be an object ↓

cause Second argument to incrementalWatcher is missing or not an object.

fix

Pass a valid options object as second argument, e.g., { name: 'my watcher' }.

Warnings

breaking Exports are from 'incremental-compiler/src' subpath, not from the package root. ↓

fix Update all imports to use 'incremental-compiler/src' instead of 'incremental-compiler'.

deprecated BaseClientCompiler constructor signature changed: it now accepts options as second parameter. ↓

fix Pass options object as second argument to super().

gotcha node_modules and .git directories are always ignored; cannot be overridden via options. ↓

fix Use a different watcher if you need to watch these directories.

gotcha incrementalWatcher expects arrays of glob patterns, not single strings. ↓

fix Always wrap a single pattern in an array: ['pattern'].

Install

npm install incremental-compiler

yarn add incremental-compiler

pnpm add incremental-compiler

Imports

BaseClientCompiler

wrong

import { BaseClientCompiler } from 'incremental-compiler'

correct

import { BaseClientCompiler } from 'incremental-compiler/src'

Exports are from the 'src' subpath; top-level import will fail.

BaseClientCompilerOptions

wrong

const { BaseClientCompilerOptions } = require('incremental-compiler')

correct

import { BaseClientCompilerOptions } from 'incremental-compiler/src'

Named export from src subpath; CJS require must use correct path.

incrementalWatcher

wrong

import { incrementalWatcher } from 'incremental-compiler'

correct

import { incrementalWatcher } from 'incremental-compiler/src'

Same as above; all exports are in src/.

Quickstart

Demonstrates setting up a file watcher with incrementalWatcher that looks for .ts files and logs changes.

import { incrementalWatcher } from 'incremental-compiler/src';

async function watchAndCompile() {
  const watcher = await incrementalWatcher(
    ['src/**/*.ts', 'src/*.ts'],
    { name: 'TS Watcher', ignoreInitial: true }
  );
  watcher.on('all', (event, filePath) => {
    console.log(`File ${event}: ${filePath}`);
    // trigger compilation
  });
}

watchAndCompile();