nft

Rastreamento do arquivo do nó

Usado para determinar exatamente quais arquivos (incluindo node_modules ) são necessários para o tempo de execução do aplicativo.

Isso é semelhante ao @vercel/ncc, exceto que não há agrupamento de agrupamento e, portanto, não depende de Webpack. Isso alcança os mesmos benefícios de troca de árvores sem mover ativos ou binários.

Uso

Instalação

npm i @vercel/nft

Uso

Forneça a lista de arquivos de origem como entrada:

 const { nodeFileTrace } = require ( '@vercel/nft' ) ;
const files = [ './src/main.js' , './src/second.js' ] ;
const { fileList } = await nodeFileTrace ( files ) ;

A lista de arquivos incluirá todos os módulos e ativos node_modules que podem ser necessários pelo código do aplicativo.

Opções

Base

O caminho base para a lista de arquivos - Todos os arquivos serão fornecidos como relativos a esta base.

Por padrão, o process.cwd() é usado:

 const { fileList } = await nodeFileTrace ( files , {
  base : process . cwd ( ) ,
} ) ;

Quaisquer arquivos/pastas acima da base são ignorados na listagem e análise.

Processo CWD

Ao aplicar a análise, certas funções dependem do valor do process.cwd() , como path.resolve('./relative') ou mesmo um process.cwd() .

A configuração da opção processCwd permite que essa análise seja guiada ao caminho certo para garantir que os ativos sejam detectados corretamente.

 const { fileList } = await nodeFileTrace ( files , {
  processCwd : path . resolve ( __dirname ) ,
} ) ;

Por padrão, processCwd é o mesmo que base .

Exportações e importações

Por padrão, o rastreamento dos campos Node.js "Exports" e "Imports" é suportado, com o "node" , "require" , "import" e "default" condições rastreadas conforme definido.

Alternativamente, a lista explícita de condições pode ser fornecida:

 const { fileList } = await nodeFileTrace ( files , {
  conditions : [ 'node' , 'production' ] ,
} ) ;

Somente a exportação do "node" deve ser explicitamente incluída (se necessário) ao especificar a lista exata da condição de exportação. As condições "require" , "import" e "default" sempre serão rastreadas conforme definido, independentemente das condições personalizadas definidas.

Apenas exportações

Ao rastrear as exportações, o campo "main" / índice ainda será rastreado para as versões Node.js sem suporte "exports" .

Isso pode ser desativado com a opção exportsOnly :

 const { fileList } = await nodeFileTrace ( files , {
  exportsOnly : true ,
} ) ;

Qualquer pacote com "exports" terá apenas suas exportações rastreadas, e o principal não será incluído. Isso pode reduzir o tamanho da saída ao direcionar o node.js 12.17.0 ou mais recente.

Caminhos

Status: Experimental. Pode mudar a qualquer momento.

Definições de caminho de resolução personalizada a ser usada.

 const { fileList } = await nodeFileTrace ( files , {
  paths : {
    'utils/' : '/path/to/utils/' ,
  } ,
} ) ;

Sobre os diretórios do mapa de barras à direita, os caminhos exatos mapeiam apenas o mapa exato.

Ganchos

As seguintes funções Fs podem ser viciadas passando -as como opções:

• readFile(path): Promise<string>
• stat(path): Promise<FS.Stats>
• readlink(path): Promise<string>
• resolve(id: string, parent: string): Promise<string | string[]>

Resolução avançada

Ao fornecer um gancho de resolução personalizado, você é responsável por retornar um ou mais caminhos absolutos para arquivos resolvidos com base na entrada id . No entanto, pode ser o caso de você apenas aumentar ou substituir o comportamento de resolução em certos casos. Você pode usar o resolvedor subjacente da nft importando -o. A função resolve incorporada espera argumentos adicionais que precisam ser encaminhados do gancho

• resolve(id: string, parent: string, job: Job, isCjs: boolean): Promise<string | string[]>

Aqui está um exemplo mostrando um ID sendo resolvido para um caminho sob medida, enquanto todos os outros caminhos sendo resolvidos pelo resolvedor interno

 const { nodeFileTrace , resolve } = require ( '@vercel/nft' ) ;
const files = [ './src/main.js' , './src/second.js' ] ;
const { fileList } = await nodeFileTrace ( files , {
  resolve : async ( id , parent , job , isCjs ) => {
    if ( id === './src/main.js' ) {
      return '/path/to/some/resolved/main/file.js' ;
    } else {
      return resolve ( id , parent , job , isCjs ) ;
    }
  } ,
} ) ; 

TypeScript

A resolução interna suporta a resolução de arquivos .ts em traços por padrão.

Por sua natureza de integração nos sistemas de compilação existentes, o compilador TypeScript não está incluído neste projeto - mas a camada de transformação do TypeScript requer integração separada no gancho readFile .

Arquivo IO Concorrência

Em alguns projetos grandes, a lógica de rastreamento de arquivos pode processar muitos arquivos ao mesmo tempo. Nesse caso, se você não limitar o número de arquivos simultâneos IO, é provável que ocorram problemas de OOM.

Utilizamos um padrão de simultaneidade 1024 para equilibrar o desempenho e o uso da memória para operações de FS. Você pode aumentar esse valor para um número maior para velocidade mais rápida, mas esteja ciente dos problemas de memória se a simultaneidade for muito alta.

 const { fileList } = await nodeFileTrace ( files , {
  fileIOConcurrency : 2048 ,
} ) ; 

Análise

As opções de análise permitem a personalização de quanta análise deve ser executada para elaborar exatamente a lista de dependência.

Por padrão, o máximo de análise possível é feito para garantir que nenhum arquivo possivelmente necessário seja deixado de fora do rastreamento.

Para desativar todas as análises, analysis: false . Como alternativa, as opções de análise individual podem ser personalizadas 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 ,
  } ,
} ) ; 

Ignorar

Ignores personalizados podem ser fornecidos para pular a inclusão de arquivos (e consequentemente a análise do arquivo para referências, por sua vez, também).

 const { fileList } = await nodeFileTrace ( files , {
  ignore : [ './node_modules/pkg/file.js' ] ,
} ) ;

Ignorar também aceitará uma função ou globs.

Observe que o caminho fornecido para ignorar é relativo à base .

Cache

Para persistir o cache do arquivo entre as compilações, passe um objeto cache vazio:

 const cache = Object . create ( null ) ;
const { fileList } = await nodeFileTrace ( [ 'index.ts' ] , { cache } ) ;
// later:
{
  const { fileList } = await nodeFileTrace ( [ 'index.ts' ] , { cache } ) ;
}

Observe que as invalidações do cache não são suportadas, portanto, a suposição é que o sistema de arquivos não é alterado entre as execuções.

Razões

Para obter os motivos subjacentes para os arquivos individuais que estão sendo incluídos, um objeto reasons também é fornecido pela saída:

 const { fileList , reasons } = await nodeFileTrace ( files ) ;

Os reasons a produção será então um objeto da seguinte forma:

 {
  [ file : string ] : {
    type : 'dependency' | 'asset' | 'sharedlib' ,
    ignored : true | false ,
    parents : string [ ]
  }
}

reasons também incluem arquivos que foram ignorados como ignored: true , com sua ignoreReason .

Cada arquivo está incluído porque é referenciado por outro arquivo. A lista parents conterá a lista de todos os arquivos que fizeram com que esse arquivo fosse incluído.