@rushstack/trace-import
v0.3.74
Published
CLI tool for understanding how require() and "import" statements get resolved
Downloads
273
Readme
@rushstack/trace-import
🚨 EARLY PREVIEW RELEASE 🚨
Not all features are implemented yet. To provide suggestions, please create a GitHub issue. If you have questions, see the Rush Stack Help page for support resources.
The trace-import
command line tool helps you:
- Analyze
import
/require()
statements to understand why they aren't resolving correctly - Understand the relationships between package folders in your
node_modules
tree - Ensure that
package.json
files correctly export their .js and .d.ts entry points
Usage
It's recommended to install this package globally:
# Install the NPM package
npm install -g @rushstack/trace-import
# View the command-line help
trace-import --help
Command line
usage: trace-import [-h] [-d] -p IMPORT_PATH [-b FOLDER_PATH] [-t {cjs,es,ts}]
This tool analyzes import module paths, to determine the resolved target
folder. For example, if the "semver" NPM package is installed, "trace-import
--path semver/index" will print output equivalent to the Node.js require.
resolve() API. If "@types/semver" is installed, then "trace-import
--resolution-type ts --path semver/index" will print the .d.ts file path that
would be resolved by a TypeScript import statement.
Optional arguments:
-h, --help Show this help message and exit.
-d, --debug Show the full call stack if an error occurs while
executing the tool
-p IMPORT_PATH, --path IMPORT_PATH
The import module path to be analyzed. For example,
"example" in expressions such as: require("example");
require.resolve("example"); import { Thing } from
"example";
-b FOLDER_PATH, --base-folder FOLDER_PATH
The "--path" string will be resolved as if the import
statement appeared in a script located in this folder.
If omitted, the current working directory is used.
-t {cjs,es,ts}, --resolution-type {cjs,es,ts}
The type of module resolution to perform: "cjs" for
CommonJS, "es" for ES modules, or "ts" for TypeScript
typings. The default value is "cjs".
Sample outputs
These commands were invoked in the C:\Git\rushstack\apps\trace-import
folder
where trace-import is developed.
Resolving a CommonJS main index
trace-import --path semver
Sample output:
Base folder: C:\Git\rushstack\apps\trace-import
Package name: semver
Package subpath: (not specified)
Resolving...
Package folder: C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\semver
package.json: semver (7.3.8)
Main index: "main": "index.js"
Target path: C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\semver\index.js
Resolving a CommonJS package subpath
trace-import --path typescript/bin/tsc
Sample output:
Base folder: C:\Git\rushstack\apps\trace-import
Package name: typescript
Package subpath: bin/tsc
Resolving...
Package folder: C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\typescript
package.json: typescript (4.8.4)
Target path: C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\typescript\bin\tsc
Resolving a TypeScript declaration
trace-import --resolution-type ts --path semver
Sample output:
Base folder: C:\Git\rushstack\apps\trace-import
Package name: semver
Package subpath: (not specified)
Resolving...
Package folder: C:\Git\rushstack\common\temp\node_modules\.pnpm\[email protected]\node_modules\semver
package.json: semver (7.3.8)
@types folder: C:\Git\rushstack\common\temp\node_modules\.pnpm\@[email protected]\node_modules\@types\semver
@types package.json: @types/semver (7.3.5)
@types main index: "types": "index.d.ts"
Target path: C:\Git\rushstack\common\temp\node_modules\.pnpm\@[email protected]\node_modules\@types\semver\index.d.ts
Resolving a relative path
trace-import --path ./config/rig.json
Sample output:
Base folder: C:\Git\rushstack\apps\trace-import
Import path: ./config/rig.json
The import path does not appear to reference an NPM package.
Resolving...
Target path: C:\Git\rushstack\apps\trace-import\config\rig.json
Links
- CHANGELOG.md - Find out what's new in the latest version
- Rush Lockfile Explorer - The desktop app for troubleshooting PNPM lockfiles
The trace-import
tool is part of the Rush Stack family of projects.