{"id":13515196,"url":"https://github.com/vercel/nft","last_synced_at":"2026-01-21T20:01:55.283Z","repository":{"id":37528248,"uuid":"195437020","full_name":"vercel/nft","owner":"vercel","description":"Node.js dependency tracing utility","archived":false,"fork":false,"pushed_at":"2025-04-21T18:16:28.000Z","size":4194,"stargazers_count":1440,"open_issues_count":43,"forks_count":155,"subscribers_count":61,"default_branch":"main","last_synced_at":"2025-05-10T02:08:25.637Z","etag":null,"topics":["static-analysis"],"latest_commit_sha":null,"homepage":"https://npmjs.com/@vercel/nft","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vercel.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-07-05T16:11:28.000Z","updated_at":"2025-05-09T07:21:32.000Z","dependencies_parsed_at":"2023-12-18T23:20:52.327Z","dependency_job_id":"9055283a-62fb-46dd-b7d7-ad86782fde46","html_url":"https://github.com/vercel/nft","commit_stats":{"total_commits":400,"total_committers":40,"mean_commits":10.0,"dds":0.5725,"last_synced_commit":"7471794a1d39e1f985a2f55d84339333873391bd"},"previous_names":["vercel/node-file-trace"],"tags_count":110,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel%2Fnft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel%2Fnft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel%2Fnft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel%2Fnft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vercel","download_url":"https://codeload.github.com/vercel/nft/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253505664,"owners_count":21918942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["static-analysis"],"created_at":"2024-08-01T05:01:07.412Z","updated_at":"2026-01-21T20:01:55.270Z","avatar_url":"https://github.com/vercel.png","language":"JavaScript","readme":"# Node File Trace\n\n[![CI Status](https://github.com/vercel/nft/actions/workflows/ci.yml/badge.svg)](https://github.com/vercel/nft/actions/workflows/ci.yml)\n\nUsed to determine exactly which files (including `node_modules`) are necessary for the application runtime.\n\nThis is similar to [@vercel/ncc](https://npmjs.com/package/@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.\n\n## Usage\n\n### Installation\n\n```bash\nnpm i @vercel/nft\n```\n\n### Usage\n\nProvide the list of source files as input:\n\n```js\nconst { nodeFileTrace } = require('@vercel/nft');\nconst files = ['./src/main.js', './src/second.js'];\nconst { fileList } = await nodeFileTrace(files);\n```\n\nThe list of files will include all `node_modules` modules and assets that may be needed by the application code.\n\n### Options\n\n#### Base\n\nThe base path for the file list - all files will be provided as relative to this base.\n\nBy default the `process.cwd()` is used:\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  base: process.cwd(),\n});\n```\n\nAny files/folders above the `base` are ignored in the listing and analysis.\n\n#### Process Cwd\n\nWhen applying analysis certain functions rely on the `process.cwd()` value, such as `path.resolve('./relative')` or even a direct `process.cwd()`\ninvocation.\n\nSetting the `processCwd` option allows this analysis to be guided to the right path to ensure that assets are correctly detected.\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  processCwd: path.resolve(__dirname),\n});\n```\n\nBy default `processCwd` is the same as `base`.\n\n#### Exports \u0026 Imports\n\nBy default tracing of the [Node.js \"exports\" and \"imports\" fields](https://nodejs.org/dist/latest-v14.x/docs/api/esm.html#esm_package_entry_points) is supported, with the `\"node\"`, `\"require\"`, `\"import\"` and `\"default\"` conditions traced as defined.\n\nAlternatively the explicit list of conditions can be provided:\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  conditions: ['node', 'production'],\n});\n```\n\nOnly 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.\n\n#### Exports Only\n\nWhen tracing exports the `\"main\"` / index field will still be traced for Node.js versions without `\"exports\"` support.\n\nThis can be disabled with the `exportsOnly` option:\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  exportsOnly: true,\n});\n```\n\nAny 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](https://github.com/nodejs/node/blob/master/doc/changelogs/CHANGELOG_V12.md#12.17.0) or newer.\n\n#### Paths\n\n\u003e Status: Experimental. May change at any time.\n\nCustom resolution path definitions to use.\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  paths: {\n    'utils/': '/path/to/utils/',\n  },\n});\n```\n\nTrailing slashes map directories, exact paths map exact only.\n\n#### Hooks\n\nThe following FS functions can be hooked by passing them as options:\n\n- `readFile(path): Promise\u003cstring\u003e`\n- `stat(path): Promise\u003cFS.Stats\u003e`\n- `readlink(path): Promise\u003cstring\u003e`\n- `resolve(id: string, parent: string): Promise\u003cstring | string[]\u003e`\n\n##### Advanced Resolving\n\nWhen providing a custom resolve hook you are responsible for returning one or more absolute paths to resolved files based on the `id` input. However it may be the case that you only want to augment or override the resolve behavior in certain cases. You can use `nft`'s underlying resolver by importing it. The builtin `resolve` function expects additional arguments that need to be forwarded from the hook\n\n- `resolve(id: string, parent: string, job: Job, isCjs: boolean): Promise\u003cstring | string[]\u003e`\n\nHere is an example showing one id being resolved to a bespoke path while all other paths being resolved by the built-in resolver\n\n```js\nconst { nodeFileTrace, resolve } = require('@vercel/nft');\nconst files = ['./src/main.js', './src/second.js'];\nconst { fileList } = await nodeFileTrace(files, {\n  resolve: async (id, parent, job, isCjs) =\u003e {\n    if (id === './src/main.js') {\n      return '/path/to/some/resolved/main/file.js';\n    } else {\n      return resolve(id, parent, job, isCjs);\n    }\n  },\n});\n```\n\n#### TypeScript\n\nThe internal resolution supports resolving `.ts` files in traces by default.\n\nBy its nature of integrating into existing build systems, the TypeScript\ncompiler is not included in this project - rather the TypeScript transform\nlayer requires separate integration into the `readFile` hook.\n\n#### File IO Concurrency\n\nIn 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.\n\nWe 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.\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  fileIOConcurrency: 2048,\n});\n```\n\n#### Analysis\n\nAnalysis options allow customizing how much analysis should be performed to exactly work out the dependency list.\n\nBy default as much analysis as possible is done to ensure no possibly needed files are left out of the trace.\n\nTo disable all analysis, set `analysis: false`. Alternatively, individual analysis options can be customized via:\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  // default\n  analysis: {\n    // whether to glob any analysis like __dirname + '/dir/' or require('x/' + y)\n    // that might output any file in a directory\n    emitGlobs: true,\n    // whether __filename and __dirname style\n    // expressions should be analyzed as file references\n    computeFileReferences: true,\n    // evaluate known bindings to assist with glob and file reference analysis\n    evaluatePureExpressions: true,\n  },\n});\n```\n\n#### Ignore\n\nCustom ignores can be provided to skip file inclusion (and consequently analysis of the file for references in turn as well).\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  ignore: ['./node_modules/pkg/file.js'],\n});\n```\n\nIgnore will also accept a function or globs.\n\nNote that the path provided to ignore is relative to `base`.\n\n#### Cache\n\nTo persist the file cache between builds, pass an empty `cache` object:\n\n```js\nconst cache = Object.create(null);\nconst { fileList } = await nodeFileTrace(['index.ts'], { cache });\n// later:\n{\n  const { fileList } = await nodeFileTrace(['index.ts'], { cache });\n}\n```\n\nNote that cache invalidations are not supported so the assumption is that the file system is not changed between runs.\n\n#### Depth\n\nThe `depth` option controls how many levels of the module graph to trace from the entry point files. This can be useful for limiting the scope of the trace or for debugging purposes:\n\n```js\nconst { fileList } = await nodeFileTrace(files, {\n  depth: 2,\n});\n```\n\nWith `depth: 0`, only the entry point files themselves are included in the trace, with no additional modules. With `depth: 1`, the entry points and their directly imported modules are traced, and so on.\n\nNote that the `depth` option cannot be less than 0. Setting a negative value will result in an error.\n\n#### Reasons\n\nTo get the underlying reasons for individual files being included, a `reasons` object is also provided by the output:\n\n```js\nconst { fileList, reasons } = await nodeFileTrace(files);\n```\n\nThe `reasons` output will then be an object of the following form:\n\n```js\n{\n  [file: string]: {\n    type: 'dependency' | 'asset' | 'sharedlib',\n    ignored: true | false,\n    parents: string[]\n  }\n}\n```\n\n`reasons` also includes files that were ignored as `ignored: true`, with their `ignoreReason`.\n\nEvery 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.\n","funding_links":[],"categories":["JavaScript","🔧 Utilities \u0026 Miscellaneous"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvercel%2Fnft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvercel%2Fnft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvercel%2Fnft/lists"}