tessl/npm-resolve

Resolve like require.resolve() on behalf of files asynchronously and synchronously

—

Pending

Overview

Eval results

Files

Command Line Interface

Name: tessl/npm-resolve
Author: tessl

Command-line tool for resolving module paths from the terminal. The CLI provides a convenient way to test module resolution and debug resolution issues without writing JavaScript code.

Capabilities

Resolve Command

Main command-line interface for module resolution.

resolve <specifier> [--preserve-symlinks]

Parameters:

<specifier> - The module specifier to resolve (required)
--preserve-symlinks - Enable symlink preservation mode (optional)

Usage Examples:

# Resolve a package from node_modules
resolve lodash
# Output: /path/to/node_modules/lodash/index.js

# Resolve a relative path
resolve ./lib/utils
# Output: /current/directory/lib/utils.js

# Resolve with symlink preservation
resolve my-package --preserve-symlinks
# Output: /path/with/symlinks/preserved

# Resolve a core module
resolve fs
# Output: fs

# Resolve a scoped package
resolve @babel/core
# Output: /path/to/node_modules/@babel/core/lib/index.js

Installation and Usage

Global Installation

npm install -g resolve
resolve <specifier>

Local Installation

npm install resolve
npx resolve <specifier>

Project Scripts

Add to package.json:

{
  "scripts": {
    "resolve": "resolve"
  }
}

Then use:

npm run resolve <specifier>

Options

Preserve Symlinks

The --preserve-symlinks option enables symlink preservation mode, equivalent to setting preserveSymlinks: true in the JavaScript API. This flag is only available when the Node.js version supports it.

resolve <specifier> --preserve-symlinks

Examples:

# Normal resolution (default)
resolve my-lib
# May resolve symlinks in the path

# With symlink preservation
resolve my-lib --preserve-symlinks
# Keeps symlinks intact in the resolved path

This option is particularly useful when working with:

npm link'd packages
Monorepos with symlinked dependencies
Development environments with symlinked modules

Resolution Context

The CLI tool resolves modules relative to the current working directory, equivalent to:

const resolve = require('resolve');
resolve.sync(specifier, { basedir: process.cwd() });

Working Directory

# Resolve from current directory
cd /my/project
resolve lodash
# Searches for lodash starting from /my/project

# Same as above but explicit
resolve lodash --basedir=/my/project  # (Not supported - use cd instead)

Exit Codes

The CLI tool uses standard exit codes to indicate success or failure:

# Exit codes:
# 0 - Success (module resolved)
# 1 - Invalid usage or command error  
# 2 - Resolution error or unknown argument

Examples:

# Successful resolution
resolve fs
echo $?  # 0

# Module not found
resolve nonexistent-module
echo $?  # 2

# Invalid usage
resolve
echo $?  # 1

# Unknown argument
resolve fs --unknown-flag
echo $?  # 2

Error Handling

Module Not Found

$ resolve nonexistent-module
Error: Cannot find module 'nonexistent-module' from '/current/directory'
$ echo $?
2

Invalid Usage

$ resolve
Error: `resolve` expects a specifier
$ echo $?
2

Unknown Arguments

$ resolve fs --unknown-flag
Unknown argument --unknown-flag
$ echo $?
2

Security Restrictions

The CLI tool includes security checks to ensure it's being run directly as an executable:

# These will work:
resolve fs
npx resolve fs
./node_modules/.bin/resolve fs

# Direct execution is required - the tool validates its execution context

Integration Examples

Shell Scripts

#!/bin/bash

# Check if a module exists before using it
if resolve lodash >/dev/null 2>&1; then
  echo "lodash is available"
  node -e "console.log(require('lodash').version)"
else
  echo "lodash not found - installing..."
  npm install lodash
fi

Build Scripts

# Verify all dependencies can be resolved
for dep in lodash express react; do
  if ! resolve "$dep" >/dev/null 2>&1; then
    echo "Error: $dep cannot be resolved"
    exit 1
  fi
done
echo "All dependencies resolved successfully"

Development Debugging

# Debug resolution issues
resolve my-problematic-module
# See exactly where the module resolves to

# Compare with and without symlink preservation
resolve linked-module
resolve linked-module --preserve-symlinks

Platform Support

The CLI tool works on all platforms supported by Node.js:

Linux
macOS
Windows

On Windows, both forward slashes and backslashes in paths are handled correctly:

# Windows examples
resolve ./lib\utils  # Works
resolve ./lib/utils  # Also works

Install with Tessl CLI

npx tessl i tessl/npm-resolve

docs