CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-node-gyp

Node.js native addon build tool

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

dev-file-management.mddocs/

Development File Management

Development file management handles the installation, listing, and removal of Node.js development files (headers and libraries) required for compiling native addons against different Node.js versions.

Capabilities

Install Command

Downloads and installs Node.js development files for a specified Node.js version, including headers, libraries, and platform-specific build artifacts.

/**
 * Install node development files for the specified node version
 * @param {Gyp} gyp - The gyp instance
 * @param {string[]} argv - Command arguments, first element can be Node.js version
 * @returns {Promise<void>}
 */
async function install(gyp: Gyp, argv: string[]): Promise<void>;

Usage Examples:

const gyp = require('node-gyp');
const gypInstance = gyp();

// Install development files for current Node.js version
await gypInstance.commands.install([]);

// Install for specific version
await gypInstance.commands.install(['16.14.0']);

// Install for latest LTS
await gypInstance.commands.install(['lts']);

// Install with options
gypInstance.opts.target = '18.0.0';
gypInstance.opts['dist-url'] = 'https://nodejs.org/dist';
await gypInstance.commands.install([]);

Installation Process:

  1. Version Resolution: Determines target Node.js version from arguments or options
  2. Download Location: Uses configured distribution URL (default: nodejs.org)
  3. Header Download: Downloads and extracts Node.js header files
  4. Library Download: Downloads platform-specific libraries (Windows: .lib files)
  5. Checksum Verification: Validates downloaded files using SHA checksums
  6. Cache Management: Stores files in development directory for reuse

List Command

Lists all currently installed Node.js development file versions in the development directory.

/**
 * Prints a listing of the currently installed node development files
 * @param {Gyp} gyp - The gyp instance
 * @param {string[]} argv - Command arguments (unused)
 * @returns {Promise<string[]>} Array of installed version strings
 */
async function list(gyp: Gyp, argv: string[]): Promise<string[]>;

Usage Examples:

const gyp = require('node-gyp');
const gypInstance = gyp();

// List all installed versions
const versions = await gypInstance.commands.list([]);
console.log('Installed versions:', versions);
// Output: ['16.14.0', '18.0.0', '18.12.1']

// Check if specific version is installed
const installedVersions = await gypInstance.commands.list([]);
const hasVersion = installedVersions.includes('16.14.0');
console.log('Has 16.14.0:', hasVersion);

Output Format:

  • Returns array of version strings for installed development files
  • Versions are sorted and deduplicated
  • Empty array if no development files are installed

Remove Command

Removes installed Node.js development files for a specified version from the development directory.

/**
 * Removes the node development files for the specified version
 * @param {Gyp} gyp - The gyp instance
 * @param {string[]} argv - Command arguments, first element should be Node.js version
 * @returns {Promise<void>}
 */
async function remove(gyp: Gyp, argv: string[]): Promise<void>;

Usage Examples:

const gyp = require('node-gyp');
const gypInstance = gyp();

// Remove specific version
await gypInstance.commands.remove(['16.14.0']);

// Remove multiple versions
await gypInstance.commands.remove(['16.14.0']);
await gypInstance.commands.remove(['18.0.0']);

// Check what's installed first
const versions = await gypInstance.commands.list([]);
console.log('Before removal:', versions);

await gypInstance.commands.remove(['16.14.0']);

const versionsAfter = await gypInstance.commands.list([]);
console.log('After removal:', versionsAfter);

Removal Process:

  1. Version Validation: Confirms the specified version exists in development directory
  2. Directory Cleanup: Removes all files and directories for that version
  3. Cache Invalidation: Cleans up any cached metadata for the version

Development Directory Structure

Node-gyp stores development files in a structured directory layout:

~/.cache/node-gyp/  (or configured devdir)
├── 16.14.0/
│   ├── include/
│   │   └── node/
│   │       ├── node.h
│   │       ├── v8.h
│   │       └── ...
│   ├── src/
│   ├── deps/
│   └── node.lib        (Windows only)
├── 18.0.0/
│   └── ...
└── 18.12.1/
    └── ...

Configuration Options

Development Directory

const gyp = require('node-gyp');
const gypInstance = gyp();

// Set custom development directory
gypInstance.opts.devdir = '/custom/path/to/dev/files';
await gypInstance.commands.install(['16.14.0']);

Distribution URL

// Use custom distribution mirror
gypInstance.opts['dist-url'] = 'https://mirror.example.com/nodejs/dist';
await gypInstance.commands.install(['16.14.0']);

// Use local tarball
gypInstance.opts.tarball = '/path/to/node-v16.14.0.tar.gz';
await gypInstance.commands.install([]);

Proxy Configuration

// Configure HTTP proxy
gypInstance.opts.proxy = 'http://proxy.company.com:8080';
gypInstance.opts.noproxy = 'localhost,127.0.0.1,.company.com';
await gypInstance.commands.install(['16.14.0']);

CA Certificate

// Use custom CA certificate file
gypInstance.opts.cafile = '/path/to/ca-certificates.crt';
await gypInstance.commands.install(['16.14.0']);

Advanced Usage Patterns

Version Management Workflow

const gyp = require('node-gyp');
const gypInstance = gyp();

// Development workflow: manage multiple Node.js versions
async function setupDevEnvironment() {
  // Install multiple versions
  await gypInstance.commands.install(['16.14.0']);
  await gypInstance.commands.install(['18.12.1']);
  await gypInstance.commands.install(['20.0.0']);
  
  // List what's available
  const versions = await gypInstance.commands.list([]);  
  console.log('Available versions:', versions);
  
  // Build against specific version
  gypInstance.opts.target = '18.12.1';
  await gypInstance.commands.configure([]);
  await gypInstance.commands.build([]);
}

Cleanup and Maintenance

const gyp = require('node-gyp');
const gypInstance = gyp();

// Clean up old versions
async function cleanupOldVersions() {
  const versions = await gypInstance.commands.list([]);
  
  // Remove versions older than 16.x
  for (const version of versions) {
    const major = parseInt(version.split('.')[0]);
    if (major < 16) {
      console.log(`Removing old version: ${version}`);
      await gypInstance.commands.remove([version]);
    }
  }
}

Conditional Installation

const gyp = require('node-gyp');
const gypInstance = gyp();

// Only install if not already present
async function ensureVersionInstalled(targetVersion) {
  const installedVersions = await gypInstance.commands.list([]);
  
  if (!installedVersions.includes(targetVersion)) {
    console.log(`Installing Node.js ${targetVersion} development files...`);
    await gypInstance.commands.install([targetVersion]);
  } else {
    console.log(`Node.js ${targetVersion} already installed`);
  }
}

// Usage
await ensureVersionInstalled('18.12.1');

ShaSum Class

The install module also exports a SHA checksum verification utility:

/**
 * Transform stream for SHA checksum verification during downloads
 * @extends Transform
 */
class ShaSum extends Transform {
  constructor(algorithm: string, expected: string);
  
  /**
   * Validates the computed hash against expected value
   * @throws {Error} If checksum doesn't match
   */
  validate(): void;
}

Usage Example:

const { ShaSum } = require('node-gyp/lib/install');
const fs = require('fs');

// Verify file checksum during streaming
const fileStream = fs.createReadStream('node-headers.tar.gz');
const shasum = new ShaSum('sha256', 'expected-hash-here');

fileStream
  .pipe(shasum)
  .on('end', () => {
    try {
      shasum.validate();
      console.log('Checksum verified successfully');
    } catch (error) {
      console.error('Checksum verification failed:', error.message);
    }
  });

Error Handling

Common error scenarios and handling:

const gyp = require('node-gyp');
const gypInstance = gyp();

try {
  await gypInstance.commands.install(['16.14.0']);
} catch (error) {
  if (error.message.includes('ENOTFOUND')) {
    console.error('Network error: Unable to reach download server');
  } else if (error.message.includes('EACCES')) {
    console.error('Permission error: Cannot write to development directory');
  } else if (error.message.includes('checksum')) {
    console.error('Download corrupted: Checksum verification failed');
  } else {
    console.error('Installation failed:', error.message);
  }
}

try {
  await gypInstance.commands.remove(['99.99.99']);
} catch (error) {
  if (error.message.includes('ENOENT')) {
    console.error('Version not found: 99.99.99 is not installed');
  }
}

docs

build-commands.md

core-build-system.md

dev-file-management.md

index.md

platform-toolchain.md

utilities.md

tile.json