tessl/npm-now--build-utils

Build utilities for Now (Vercel) serverless platform runtime development

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Script Execution

Name: tessl/npm-now--build-utils
Author: tessl

Tools for executing build scripts, package manager commands, and shell operations with proper environment setup.

Capabilities

Async Command Execution

Execute commands asynchronously and capture their output.

/**
 * Execute command asynchronously and capture output
 * @param command - Command to execute
 * @param args - Command arguments
 * @param opts - Spawn options
 * @returns Promise resolving to execution result
 */
function execAsync(
  command: string, 
  args: string[], 
  opts?: SpawnOptions
): Promise<{ stdout: string; stderr: string; code: number }>;

Usage Examples:

import { execAsync } from "@now/build-utils";

// Run git command and capture output
const result = await execAsync("git", ["rev-parse", "HEAD"], {
  cwd: "/project"
});
console.log("Commit hash:", result.stdout.trim());

// Check if command succeeded
if (result.code === 0) {
  console.log("Command succeeded");
} else {
  console.error("Command failed:", result.stderr);
}

Async Process Spawning

Spawn processes asynchronously with inherited stdio for real-time output.

/**
 * Spawn process asynchronously
 * @param command - Command to spawn
 * @param args - Command arguments  
 * @param opts - Spawn options
 * @returns Promise that resolves when process completes successfully
 */
function spawnAsync(
  command: string,
  args: string[],
  opts?: SpawnOptions
): Promise<void>;

Usage Examples:

import { spawnAsync } from "@now/build-utils";

// Run build command with real-time output
await spawnAsync("npm", ["run", "build"], {
  cwd: "/project",
  stdio: "inherit"
});

// Install dependencies silently
await spawnAsync("yarn", ["install"], {
  cwd: "/project",
  stdio: "pipe"
});

Shell Command Execution

Execute shell commands with proper cross-platform support.

/**
 * Execute shell command with cross-platform support
 * @param command - Shell command to execute
 * @param options - Spawn options
 * @returns Promise that resolves when command completes
 */
function execCommand(command: string, options?: SpawnOptions): Promise<boolean>;

/**
 * Spawn shell command with cross-platform support
 * @param command - Shell command to spawn
 * @param options - Spawn options
 * @returns Child process instance
 */
function spawnCommand(command: string, options?: SpawnOptions): ChildProcess;

Package Manager Operations

NPM Operations

Run npm install and related commands with proper configuration.

/**
 * Run npm install with proper options
 * @param destPath - Directory to run npm install in
 * @param args - Additional npm arguments
 * @param spawnOpts - Spawn options
 * @param meta - Build metadata
 */
function runNpmInstall(
  destPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions,
  meta?: Meta
): Promise<void>;

Usage Examples:

import { runNpmInstall } from "@now/build-utils";

// Install dependencies
await runNpmInstall("/project");

// Install with additional args
await runNpmInstall("/project", ["--production"]);

// Install in development mode
await runNpmInstall("/project", [], {}, { isDev: true });

Bundle Install (Ruby)

Run bundle install for Ruby projects.

/**
 * Run bundle install for Ruby projects
 * @param destPath - Directory containing Gemfile
 * @param args - Additional bundle arguments
 * @param spawnOpts - Spawn options
 * @param meta - Build metadata
 */
function runBundleInstall(
  destPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions,
  meta?: Meta
): Promise<void>;

Pip Install (Python)

Run pip install for Python projects.

/**
 * Run pip install for Python projects
 * @param destPath - Directory containing requirements
 * @param args - Additional pip arguments
 * @param spawnOpts - Spawn options
 * @param meta - Build metadata
 */
function runPipInstall(
  destPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions,
  meta?: Meta
): Promise<void>;

Legacy Dependency Installation

@deprecated - Use runNpmInstall() instead.

/**
 * @deprecated Install dependencies - use runNpmInstall() instead
 * @param destPath - Directory to install dependencies in
 * @param args - Additional npm arguments
 * @param spawnOpts - Spawn options
 * @param meta - Build metadata
 */
function installDependencies(
  destPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions,
  meta?: Meta
): Promise<void>;

Package.json Script Execution

Run npm scripts defined in package.json.

/**
 * Run npm script from package.json
 * @param destPath - Directory containing package.json
 * @param scriptName - Name of script to run
 * @param spawnOpts - Spawn options
 * @returns Promise resolving to true if script exists and runs successfully
 */
function runPackageJsonScript(
  destPath: string,
  scriptName: string,
  spawnOpts?: SpawnOptions
): Promise<boolean>;

Usage Examples:

import { runPackageJsonScript } from "@now/build-utils";

// Run build script
const buildExists = await runPackageJsonScript("/project", "build");
if (!buildExists) {
  console.log("No build script found");
}

// Run with custom options
await runPackageJsonScript("/project", "test", {
  env: { NODE_ENV: "test" }
});

Shell Script Execution

Execute shell scripts with proper environment setup.

/**
 * Run shell script with proper environment and permissions
 * @param fsPath - Absolute path to shell script
 * @param args - Arguments to pass to script
 * @param spawnOpts - Spawn options
 */
function runShellScript(
  fsPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions
): Promise<boolean>;

Node.js Version Management

Get Node Version for Build

Determine the appropriate Node.js version for a build.

/**
 * Get Node.js version for build
 * @param destPath - Project directory
 * @param undefined - Unused parameter (legacy API)
 * @param config - Build configuration
 * @param meta - Build metadata
 * @returns Promise resolving to NodeVersion information
 */
function getNodeVersion(
  destPath: string,
  undefined?: any,
  config?: Config,
  meta?: Meta
): Promise<NodeVersion>;

interface NodeVersion {
  major: number;
  range: string;
  runtime: string;
  discontinueDate?: Date;
}

Environment Options

Get spawn options with proper environment variables.

/**
 * Get spawn options with proper environment
 * @param meta - Build metadata
 * @param nodeVersion - Node.js version information
 * @returns Spawn options with configured environment
 */
function getSpawnOptions(meta?: Meta, nodeVersion?: NodeVersion): SpawnOptions;

Usage Examples:

import { getNodeVersion, getSpawnOptions } from "@now/build-utils";

// Get Node version for project
const nodeVersion = await getNodeVersion("/project", undefined, config);
console.log(`Using Node.js ${nodeVersion.range}`);

// Get spawn options with proper environment
const spawnOpts = getSpawnOptions(meta, nodeVersion);
await spawnAsync("node", ["build.js"], spawnOpts);