Grunt Node Inspector

Grunt Node Inspector is a Grunt plugin that integrates node-inspector into Grunt workflows for debugging Node.js applications. It provides a convenient way to configure and run node-inspector as a Grunt task with extensive customization options including port configuration, SSL support, debugging settings, and UI visibility controls.

Package Information

• Package Name: grunt-node-inspector
• Package Type: npm
• Language: JavaScript
• Installation: npm install grunt-node-inspector --save-dev

Core Imports

After installation, load the plugin in your Gruntfile:

grunt.loadNpmTasks('grunt-node-inspector');

Basic Usage

The minimal usage of node-inspector runs with no options:

module.exports = function(grunt) {
  grunt.initConfig({
    'node-inspector': {
      dev: {}
    }
  });
  
  grunt.loadNpmTasks('grunt-node-inspector');
};

When this task is run with grunt node-inspector:dev, node-inspector will be available at 0.0.0.0:8080.

Capabilities

Task Configuration

Configure the node-inspector Grunt task with various options for debugging Node.js applications.

/**
 * Grunt task configuration for node-inspector
 */
'node-inspector': {
  [target: string]: {
    options?: NodeInspectorOptions;
  };
}

interface NodeInspectorOptions {
  /** Port to connect to the debugging app (default: 5858) */
  'debug-port'?: number;
  /** Host to listen on (default: '0.0.0.0') */
  'web-host'?: string;
  /** Port to host the inspector (default: 8080) */
  'web-port'?: number;
  /** Save live edit changes to disk (default: false) */
  'save-live-edit'?: boolean;
  /** Enables preloading *.js files. Set to false to speed up startup (default: true) */
  'preload'?: boolean;
  /** Array of files to hide from the UI (breakpoints in these files will be ignored) */
  'hidden'?: string[];
  /** Number of stack frames to show on a breakpoint (default: 50) */
  'stack-trace-limit'?: number;
  /** File containing a valid SSL key for HTTPS inspector */
  'ssl-key'?: string;
  /** File containing a valid SSL certificate for HTTPS inspector */
  'ssl-cert'?: string;
}

Basic Configuration Example:

module.exports = function(grunt) {
  grunt.initConfig({
    'node-inspector': {
      dev: {
        options: {
          'web-port': 1337,
          'debug-port': 5857
        }
      }
    }
  });
  
  grunt.loadNpmTasks('grunt-node-inspector');
};

Advanced Configuration Example:

module.exports = function(grunt) {
  grunt.initConfig({
    'node-inspector': {
      custom: {
        options: {
          'web-host': 'localhost',
          'web-port': 1337,
          'debug-port': 5857,
          'save-live-edit': true,
          'preload': false,
          'hidden': ['node_modules'],
          'stack-trace-limit': 4
        }
      }
    }
  });
  
  grunt.loadNpmTasks('grunt-node-inspector');
};

HTTPS Configuration Example:

module.exports = function(grunt) {
  grunt.initConfig({
    'node-inspector': {
      https: {
        options: {
          'web-host': 'localhost',
          'web-port': 1337,
          'debug-port': 5857,
          'ssl-key': './ssl/key.pem',
          'ssl-cert': './ssl/cert.pem'
        }
      }
    }
  });
  
  grunt.loadNpmTasks('grunt-node-inspector');
};

Plugin Registration

The plugin exports a function that registers the node-inspector task with Grunt.

/**
 * Plugin entry point - registers the node-inspector multi-task
 * @param grunt - The Grunt object
 */
module.exports = function(grunt) {
  // Registers 'node-inspector' multi-task with Grunt
};

Task Execution

Execute the node-inspector task with Grunt CLI commands.

# Run specific target
grunt node-inspector:dev
grunt node-inspector:custom

# Run default target (if configured)
grunt node-inspector

Configuration Options

debug-port

Port to connect to the debugging app.

• Type: number
• Default: 5858
• Description: The port where your Node.js application is running with debug mode enabled

web-host

Host to listen on for the web interface.

• Type: string
• Default: '0.0.0.0'
• Description: The hostname or IP address where the inspector web interface will be accessible

web-port

Port to host the inspector web interface.

• Type: number
• Default: 8080
• Description: The port where the node-inspector web interface will be served

save-live-edit

Save live edit changes to disk.

• Type: boolean
• Default: false
• Description: When enabled, changes made in the inspector will be saved back to the original source files

preload

Enables preloading *.js files.

• Type: boolean
• Default: true
• Description: Set to false to speed up startup by not preloading JavaScript files

hidden

Array of files to hide from the UI.

• Type: string[]
• Default: []
• Description: Files or directories to hide from the debugging interface. Breakpoints in these files will be ignored. Commonly used to hide node_modules

stack-trace-limit

Number of stack frames to show on a breakpoint.

• Type: number
• Default: 50
• Description: Limits the number of stack frames displayed in the debugger to improve performance

ssl-key

SSL key file for HTTPS inspector.

• Type: string
• Default: ''
• Description: Path to a file containing a valid SSL private key for starting inspector over HTTPS

ssl-cert

SSL certificate file for HTTPS inspector.

• Type: string
• Default: ''
• Description: Path to a file containing a valid SSL certificate for starting inspector over HTTPS

Error Handling

The plugin will terminate the Grunt process if node-inspector fails to start:

• Network issues: If the specified ports are already in use
• SSL issues: If SSL key/certificate files are invalid or missing
• Node-inspector errors: If the underlying node-inspector process encounters errors

When errors occur, check:

1. Port availability (web-port and debug-port)
2. SSL certificate validity (if using HTTPS)
3. Node-inspector dependency installation
4. File permissions for SSL certificates