tessl/npm-vercel--build-utils

Build utilities for Vercel platform builders and serverless functions, providing utilities for creating and managing Lambda functions, file operations, and build-time helpers for the Vercel deployment platform

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Process Execution

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

Utilities for executing shell commands, installing dependencies, and running user scripts safely in the Vercel build environment.

Capabilities

Async Process Execution

spawnAsync

Spawns a child process asynchronously with promise-based interface.

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

interface SpawnOptionsExtended extends SpawnOptions {
  prettyCommand?: string;
}

Usage Examples:

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

// Install npm dependencies
await spawnAsync("npm", ["install"], {
  cwd: "/project",
  stdio: "inherit"
});

// Run build script
await spawnAsync("npm", ["run", "build"], {
  cwd: "/project",
  env: { NODE_ENV: "production" }
});

// Execute with custom display name
await spawnAsync("node", ["build.js"], {
  cwd: "/project",
  prettyCommand: "Custom Build Script"
});

// Run with piped output
await spawnAsync("eslint", ["src/"], {
  cwd: "/project",
  stdio: "pipe"
});

execAsync

Executes a command and returns stdout, stderr, and exit code.

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

Usage Examples:

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

// Get command output
const result = await execAsync("node", ["--version"], {
  cwd: "/project"
});
console.log(`Node version: ${result.stdout.trim()}`);

// Check build status
const buildResult = await execAsync("npm", ["run", "test"], {
  cwd: "/project"
});

if (buildResult.code === 0) {
  console.log("Tests passed!");
} else {
  console.error("Tests failed:", buildResult.stderr);
}

// Get git information
const gitResult = await execAsync("git", ["rev-parse", "HEAD"], {
  cwd: "/project"
});
const commitHash = gitResult.stdout.trim();

Command Utilities

spawnCommand

Spawns a command with simplified options.

/**
 * Spawns command with options
 * @param command - Full command string
 * @param options - Spawn options
 * @returns Child process instance
 */
function spawnCommand(command: string, options?: SpawnOptions): ChildProcess;

execCommand

Executes a command with simplified interface.

/**
 * Executes command with options
 * @param command - Full command string
 * @param options - Execution options
 * @returns Promise resolving to true when complete
 */
function execCommand(command: string, options?: SpawnOptions): Promise<boolean>;

Dependency Installation

installDependencies

Installs project dependencies using the appropriate package manager.

/**
 * Installs project dependencies
 * @param options - Installation options
 * @returns Promise that resolves when installation completes
 */
function installDependencies(options: InstallDependenciesOptions): Promise<void>;

interface InstallDependenciesOptions {
  workPath: string;
  meta?: Meta;
  args?: string[];
}

Usage Examples:

import { installDependencies } from "@vercel/build-utils";

// Install dependencies
await installDependencies({
  workPath: "/project"
});

// Install with custom args
await installDependencies({
  workPath: "/project",
  args: ["--production", "--no-optional"]
});

// Install in dev mode
await installDependencies({
  workPath: "/project",
  meta: { isDev: true }
});

runNpmInstall

Runs npm install with appropriate configuration.

/**
 * Runs npm install
 * @param workPath - Project directory
 * @param args - Additional npm arguments
 * @param spawnOpts - Spawn options
 * @param meta - Build metadata
 * @returns Promise that resolves when installation completes
 */
function runNpmInstall(
  workPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions,
  meta?: Meta
): Promise<void>;

runBundleInstall

Runs bundle install for Ruby projects.

/**
 * Runs bundle install (Ruby)
 * @param workPath - Project directory
 * @param args - Additional bundle arguments
 * @param spawnOpts - Spawn options
 * @returns Promise that resolves when installation completes
 */
function runBundleInstall(
  workPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions
): Promise<void>;

runPipInstall

Runs pip install for Python projects.

/**
 * Runs pip install (Python)
 * @param workPath - Project directory
 * @param args - Additional pip arguments
 * @param spawnOpts - Spawn options
 * @returns Promise that resolves when installation completes
 */
function runPipInstall(
  workPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions
): Promise<void>;

Script Execution

runPackageJsonScript

Runs a script defined in package.json.

/**
 * Runs npm script from package.json
 * @param workPath - Project directory
 * @param scriptName - Script name to run
 * @param spawnOpts - Spawn options
 * @returns Promise that resolves when script completes
 */
function runPackageJsonScript(
  workPath: string,
  scriptName: string,
  spawnOpts?: SpawnOptions
): Promise<void>;

Usage Examples:

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

// Run build script
await runPackageJsonScript("/project", "build");

// Run tests
await runPackageJsonScript("/project", "test", {
  env: { CI: "true" }
});

// Run custom script
await runPackageJsonScript("/project", "deploy:prod");

runShellScript

Runs a shell script file.

/**
 * Runs shell script
 * @param scriptPath - Path to script file
 * @param args - Script arguments
 * @param spawnOpts - Spawn options
 * @returns Promise that resolves when script completes
 */
function runShellScript(
  scriptPath: string,
  args?: string[],
  spawnOpts?: SpawnOptions
): Promise<void>;

File System Utilities

walkParentDirs

Walks up parent directories to find a specific file or directory.

/**
 * Walks up parent directories
 * @param options - Walk options
 * @returns Promise resolving to path to found item or null
 */
function walkParentDirs(options: WalkParentDirsProps): Promise<string | null>;

interface WalkParentDirsProps {
  base: string;
  start: string;
  filename: string;
}

Usage Examples:

import { walkParentDirs } from "@vercel/build-utils";

// Find package.json in parent directories
const packageJsonPath = await walkParentDirs({
  base: "/project",
  start: "/project/src/components",
  filename: "package.json"
});

// Find .git directory
const gitDir = await walkParentDirs({
  base: "/project",
  start: "/project/nested/deep",
  filename: ".git"
});

// Find configuration file
const configPath = await walkParentDirs({
  base: "/app",
  start: "/app/src",
  filename: "vercel.json"
});

getScriptName

Gets script name from package.json.

/**
 * Gets script name from package.json
 * @param workPath - Project directory
 * @param possibleNames - Possible script names to check
 * @returns Found script name or null
 */
function getScriptName(workPath: string, possibleNames: string[]): string | null;

Node.js Utilities

getNodeVersion

Gets Node.js version information for the runtime.

/**
 * Gets Node.js version information
 * @param workPath - Project directory
 * @param nodeVersion - Requested Node.js version
 * @returns Promise resolving to Node version info
 */
function getNodeVersion(workPath: string, nodeVersion?: string): Promise<NodeVersion>;

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

getNodeBinPath

Gets the path to Node.js binary for the runtime.

/**
 * Gets Node.js binary path
 * @param options - Options with cwd property
 * @returns Promise resolving to Node.js binary path
 */
function getNodeBinPath(options: { cwd: string }): Promise<string>;

getSpawnOptions

Gets spawn options configured for the build environment.

/**
 * Gets spawn options for child processes
 * @param meta - Build metadata
 * @param nodeVersion - Node version info
 * @returns Configured spawn options
 */
function getSpawnOptions(meta: Meta, nodeVersion: NodeVersion): SpawnOptions;

Error Handling

All process execution functions throw NowBuildError on failure:

import { spawnAsync, NowBuildError } from "@vercel/build-utils";

try {
  await spawnAsync("npm", ["run", "build"]);
} catch (error) {
  if (error instanceof NowBuildError) {
    console.error(`Build failed: ${error.message}`);
    console.error(`Error code: ${error.code}`);
  }
}

Environment Configuration

Process execution respects environment variables and build metadata:

import { spawnAsync, getNodeVersion } from "@vercel/build-utils";

// Configure Node.js version
const nodeVersion = await getNodeVersion("/project", "18.x");

// Execute with proper environment
await spawnAsync("node", ["build.js"], {
  cwd: "/project",
  env: {
    NODE_ENV: "production",
    PATH: `${await getNodeBinPath({ cwd: "/project" })}:${process.env.PATH}`
  }
});

Install with Tessl CLI

npx tessl i tessl/npm-vercel--build-utils

docs

platform-utilities.md

process-execution.md

tile.json

tessl/npm-vercel--build-utils