Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
@vercel/nft
Advanced tools
[![CI Status](https://github.com/vercel/nft/actions/workflows/ci.yml/badge.svg)](https://github.com/vercel/nft/actions/workflows/ci.yml) [![Code Coverage](https://badgen.net/codecov/c/github/vercel/nft)](https://codecov.io/gh/vercel/nft)
The @vercel/nft (Node File Tracer) package is a tool used to trace the files that are required by a Node.js application or module at runtime. It is primarily used to determine the minimal set of files necessary to run a Node.js application, which is useful for creating lightweight Docker containers, serverless deployments, and reducing deployment package sizes.
File Tracing
This feature allows you to trace the files that are required by a specific entry point file or set of files. The function `nodeFileTrace` takes an array of file paths and returns a list of all the files that are needed to execute them, including node_modules dependencies.
const { nodeFileTrace } = require('@vercel/nft');
(async () => {
const files = await nodeFileTrace(['path/to/your/file.js']);
console.log(files);
})();
The 'pkg' package is used to package Node.js projects into executable binaries. While it does not perform file tracing like @vercel/nft, it also aims to include only the necessary files to run the application, which is a similar end goal.
The 'ncc' package, also by Vercel, compiles a Node.js module into a single file, including all its dependencies. It is similar to @vercel/nft in that it helps to bundle only what is necessary for deployment, but it does so by compiling the code rather than tracing file dependencies.
This Webpack plugin is used to exclude node_modules when bundling a Node.js application with Webpack. It is similar to @vercel/nft in the sense that it helps to reduce the size of the deployment by excluding unnecessary files, but it does so as part of the Webpack bundling process.
Used to determine exactly which files (including node_modules
) are necessary for the application runtime.
This is similar to @vercel/ncc except there is no bundling performed and therefore no reliance on webpack. This achieves the same tree-shaking benefits without moving any assets or binaries.
npm i @vercel/nft
Provide the list of source files as input:
const { nodeFileTrace } = require('@vercel/nft');
const files = ['./src/main.js', './src/second.js'];
const { fileList } = await nodeFileTrace(files);
The list of files will include all node_modules
modules and assets that may be needed by the application code.
The base path for the file list - all files will be provided as relative to this base.
By default the process.cwd()
is used:
const { fileList } = await nodeFileTrace(files, {
base: process.cwd()
}
Any files/folders above the base
are ignored in the listing and analysis.
When applying analysis certain functions rely on the process.cwd()
value, such as path.resolve('./relative')
or even a direct process.cwd()
invocation.
Setting the processCwd
option allows this analysis to be guided to the right path to ensure that assets are correctly detected.
const { fileList } = await nodeFileTrace(files, {
processCwd: path.resolve(__dirname)
}
By default processCwd
is the same as base
.
By default tracing of the Node.js "exports" and "imports" fields is supported, with the "node"
, "require"
, "import"
and "default"
conditions traced as defined.
Alternatively the explicit list of conditions can be provided:
const { fileList } = await nodeFileTrace(files, {
conditions: ['node', 'production']
});
Only the "node"
export should be explicitly included (if needed) when specifying the exact export condition list. The "require"
, "import"
and "default"
conditions will always be traced as defined, no matter what custom conditions are set.
When tracing exports the "main"
/ index field will still be traced for Node.js versions without "exports"
support.
This can be disabled with the exportsOnly
option:
const { fileList } = await nodeFileTrace(files, {
exportsOnly: true
});
Any package with "exports"
will then only have its exports traced, and the main will not be included at all. This can reduce the output size when targeting Node.js 12.17.0 or newer.
Status: Experimental. May change at any time.
Custom resolution path definitions to use.
const { fileList } = await nodeFileTrace(files, {
paths: {
'utils/': '/path/to/utils/'
}
});
Trailing slashes map directories, exact paths map exact only.
The following FS functions can be hooked by passing them as options:
readFile(path): Promise<string>
stat(path): Promise<FS.Stats>
readlink(path): Promise<string>
resolve(id: string, parent: string): Promise<string | string[]>
The internal resolution supports resolving .ts
files in traces by default.
By its nature of integrating into existing build systems, the TypeScript
compiler is not included in this project - rather the TypeScript transform
layer requires separate integration into the readFile
hook.
In some large projects, the file tracing logic may process many files at the same time. In this case, if you do not limit the number of concurrent files IO, OOM problems are likely to occur.
We use a default of 1024 concurrency to balance performance and memory usage for fs operations. You can increase this value to a higher number for faster speed, but be aware of the memory issues if the concurrency is too high.
const { fileList } = await nodeFileTrace(files, {
fileIOConcurrency: 2048,
});
Analysis options allow customizing how much analysis should be performed to exactly work out the dependency list.
By default as much analysis as possible is done to ensure no possibly needed files are left out of the trace.
To disable all analysis, set analysis: false
. Alternatively, individual analysis options can be customized via:
const { fileList } = await nodeFileTrace(files, {
// default
analysis: {
// whether to glob any analysis like __dirname + '/dir/' or require('x/' + y)
// that might output any file in a directory
emitGlobs: true,
// whether __filename and __dirname style
// expressions should be analyzed as file references
computeFileReferences: true,
// evaluate known bindings to assist with glob and file reference analysis
evaluatePureExpressions: true,
}
});
Custom ignores can be provided to skip file inclusion (and consequently analysis of the file for references in turn as well).
const { fileList } = await nodeFileTrace(files, {
ignore: ['./node_modules/pkg/file.js']
});
Ignore will also accept a function or globs.
Note that the path provided to ignore is relative to base
.
To persist the file cache between builds, pass an empty cache
object:
const cache = Object.create(null);
const { fileList } = await nodeFileTrace(['index.ts'], { cache });
// later:
{
const { fileList } = await nodeFileTrace(['index.ts'], { cache });
}
Note that cache invalidations are not supported so the assumption is that the file system is not changed between runs.
To get the underlying reasons for individual files being included, a reasons
object is also provided by the output:
const { fileList, reasons } = await nodeFileTrace(files);
The reasons
output will then be an object of the following form:
{
[file: string]: {
type: 'dependency' | 'asset' | 'sharedlib',
ignored: true | false,
parents: string[]
}
}
reasons
also includes files that were ignored as ignored: true
, with their ignoreReason
.
Every file is included because it is referenced by another file. The parents
list will contain the list of all files that caused this file to be included.
FAQs
[![CI Status](https://github.com/vercel/nft/actions/workflows/ci.yml/badge.svg)](https://github.com/vercel/nft/actions/workflows/ci.yml)
We found that @vercel/nft demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.