or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-api.mdevents.mdindex.md
tile.json

tessl/npm-nodemon

Simple monitor script for use during development of a Node.js app.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/nodemon@3.1.x

To install, run

npx @tessl/cli install tessl/npm-nodemon@3.1.0

index.mddocs/

Nodemon

Nodemon is a development tool that automatically monitors Node.js applications and restarts them when file changes are detected in the directory. It serves as a drop-in replacement wrapper for the node command, requiring no changes to existing code or development workflows.

Package Information

  • Package Name: nodemon
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install -g nodemon or npm install --save-dev nodemon

Core Imports

For programmatic usage (as a library):

const nodemon = require('nodemon');

For CommonJS with destructuring:

const { config } = require('nodemon');

For TypeScript (using CommonJS export pattern):

import nodemon = require('nodemon');
import type { NodemonSettings, NodemonConfig } from 'nodemon';

// Alternative ES module style (requires esModuleInterop)
import nodemon from 'nodemon';
import type { NodemonSettings, NodemonConfig } from 'nodemon';

Basic Usage

CLI Usage

# Basic usage - monitors current directory and restarts on file changes
nodemon app.js

# With specific extensions
nodemon --ext js,json,ts app.js

# With custom watch directories
nodemon --watch src --watch config app.js

# With ignore patterns
nodemon --ignore test/ --ignore logs/ app.js

Programmatic Usage

const nodemon = require('nodemon');

// Object configuration
nodemon({
  script: 'app.js',
  ext: 'js json ts',
  watch: ['src/', 'config/'],
  ignore: ['test/', 'logs/']
});

// String configuration (CLI-style)
nodemon('--ext js,json app.js');

// Event handling
nodemon.on('start', function () {
  console.log('App has started');
}).on('quit', function () {
  console.log('App has quit');
  process.exit();
}).on('restart', function (files) {
  console.log('App restarted due to: ', files);
});

Architecture

Nodemon is built around several key components:

  • Main Function: The primary nodemon() function that can accept configuration objects or CLI-style strings
  • Event System: Built-in event emitter for monitoring application lifecycle (start, restart, quit, crash)
  • File Monitoring: Uses Chokidar for efficient file system watching with ignore patterns and custom rules
  • Process Management: Handles child process spawning, restarting, and signal forwarding
  • Configuration System: Supports JSON config files, CLI arguments, and programmatic options
  • CLI Interface: Command-line tool with comprehensive argument parsing and help system

Capabilities

Core API

The main nodemon function and essential control methods for starting, restarting, and managing monitored processes.

/**
 * Main nodemon function - starts monitoring with given settings
 * @param settings - Configuration object or CLI-style string
 * @returns Nodemon instance for chaining
 */
function nodemon(settings: NodemonSettings | string): Nodemon;

interface Nodemon {
  /** Manually restart the monitored process */
  restart(): Nodemon;
  
  /** Reset nodemon to clean state (useful for testing) */
  reset(callback?: Function): Nodemon;
  
  /** Reference to internal configuration */
  config: NodemonSettings;
  
  /** Dynamic stdout stream (available when stdout: false is configured) */
  stdout?: NodeJS.ReadableStream;
  
  /** Dynamic stderr stream (available when stdout: false is configured) */
  stderr?: NodeJS.ReadableStream;
}

Core API

Event System

Event emitter interface for monitoring application lifecycle and handling custom events.

interface NodemonEventListener {
  /** Add event listener for nodemon events */
  on(event: 'start' | 'crash' | 'readable', listener: () => void): Nodemon;
  on(event: 'log', listener: (e: NodemonEventLog) => void): Nodemon;
  on(event: 'stdout' | 'stderr', listener: (e: string) => void): Nodemon;
  on(event: 'restart', listener: (e?: NodemonEventRestart) => void): Nodemon;
  on(event: 'quit', listener: (e?: NodemonEventQuit) => void): Nodemon;
  on(event: 'exit', listener: (e?: number) => void): Nodemon;
  on(event: 'config:update', listener: (e?: NodemonEventConfig) => void): Nodemon;
}

type NodemonEventHandler = 'start' | 'crash' | 'exit' | 'quit' | 'restart' | 'config:update' | 'log' | 'readable' | 'stdout' | 'stderr';

Event System

Configuration

Comprehensive configuration options for file watching, process execution, and monitoring behavior.

interface NodemonSettings extends NodemonConfig, NodemonExecOptions {
  events?: Record<string, string>;
  env?: Record<string, string>;
}

interface NodemonConfig {
  restartable?: false | string;
  colours?: boolean;
  watch?: string[];
  ignore?: string[];
  ext?: string;
  verbose?: boolean;
  stdout?: boolean;
  delay?: number;
  // ... additional configuration options
}

Configuration

Types

Event Types

type NodemonEventHandler = 
  | 'start' 
  | 'crash' 
  | 'exit' 
  | 'quit' 
  | 'restart' 
  | 'config:update' 
  | 'log' 
  | 'readable' 
  | 'stdout' 
  | 'stderr';

interface NodemonEventLog {
  /** Log level: detail, log, status, error, fail */
  type: 'detail' | 'log' | 'status' | 'error' | 'fail';
  /** Plain text message */
  message: string;
  /** Terminal escape codes with color and "[nodemon]" prefix */
  colour: string;
}

interface NodemonEventRestart {
  matched?: {
    result: string[];
    total: number;
  };
}

type NodemonEventQuit = 143 | 130;

Configuration Types

interface NodemonExecOptions {
  script: string;
  scriptPosition?: number;
  args?: string[];
  ext?: string;
  exec?: string;
  execArgs?: string[];
  nodeArgs?: string[];
}

interface NodemonEventConfig {
  run: boolean;
  system: {
    cwd: string;
  };
  required: boolean;
  dirs: string[];
  timeout: number;
  options: NodemonConfig;
  lastStarted: number;
  loaded: string[];
  load: (settings: NodemonSettings, ready: (config: NodemonEventConfig) => void) => void;
  reset: () => void;
}