@vercel/nft
    TypeScript icon, indicating that this package has built-in type declarations

    0.17.3 • Public • Published

    Node File Trace

    CI Status Code Coverage

    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.

    Usage

    Installation

    npm i @vercel/nft

    Usage

    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.

    Options

    Base

    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.

    Process Cwd

    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.

    Exports & Imports

    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.

    Exports Only

    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.

    Paths

    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.

    Hooks

    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[]>

    TypeScript

    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.

    Analysis

    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,
      }
    });

    Ignore

    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.

    Cache

    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.

    Reasons

    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.

    Keywords

    none

    Install

    npm i @vercel/nft

    DownloadsWeekly Downloads

    166,911

    Version

    0.17.3

    License

    MIT

    Unpacked Size

    286 kB

    Total Files

    39

    Last publish

    Collaborators

    • crowterli
    • gsoltis
    • schlez
    • epallerols
    • domysee
    • nwienert
    • arbw
    • gudmundur
    • marcgreenstock
    • stephdietz
    • vvo
    • falcoagustin
    • nabsul
    • bmealey
    • brethudson
    • maedahbatool
    • matt.straka
    • jasongullickson
    • f3d0r
    • gaspar09
    • jtaylor0196
    • pieparker
    • kelly
    • dferber90
    • healeycodes
    • broph123
    • codybrouwers
    • ebb-tide
    • gdborton
    • msimulcik
    • jeffreyarneson
    • jaredpalmer
    • kikobeats
    • domeccleston
    • nutlope
    • hungrybearstudio
    • codetaromiura
    • mattcleg
    • gkaragkiaouris
    • geovanisouza92
    • dglsparsons
    • lostinpatterns
    • pralhad-vercel
    • vercel-release-bot
    • williamli
    • southpolesteve
    • goncy
    • chibicode
    • ijjk
    • andybitz
    • iamevilrabbit
    • joecohens
    • tootallnate
    • styfle
    • zeit-bot
    • quietshu
    • hankvercel
    • mglagola
    • javivelasco
    • igorklopov
    • paco
    • dav-is
    • timer
    • lucleray
    • leerobinson
    • matheuss
    • nkzawa
    • anatrajkovska
    • timneutkens
    • elsigh
    • cl3arglass
    • samsisle
    • chriswdmr
    • rizbizkits
    • ernestd
    • ismaelrumzan
    • jhoch
    • mrmckeb
    • kuvos
    • creationix
    • rauchg
    • huozhi
    • aadityajshah
    • cmvnk
    • lfades
    • paulogdm
    • ktcarter
    • okbel
    • padmaia
    • msweeneydev
    • delba
    • catsaremlg
    • steventey
    • sokra
    • gsandhu
    • dbredvick
    • kdy1