Para verificar o que um pacote partilhado de npm workspace irá realmente fornecer, execute os seus testes a partir do monorepo, empacote o workspace e, em seguida, instale esse tarball num diretório de consumidor temporário e separado no seu Mac. Isto deteta problemas ocultados pelo symlink local do workspace do npm, tais como ficheiros compilados em falta ou um ponto de entrada incorreto do pacote. Não publica nada num registo.

1. Execute os testes do próprio pacote a partir da raiz do workspace

Abra o Terminal e mude para a raiz do monorepo — o diretório que contém o package.json raiz. Confirme que o pacote aparece na configuração workspaces raiz e que tem o seu próprio package.json. O npm instala os workspaces configurados como ligações no node_modules da raiz, pelo que uma execução de testes aí pode resolver o código-fonte em tempo real do workspace. A opção de workspace permite-lhe visar um pacote pelo seu nome declarado ou diretório. npm Workspaces

Execute o script de teste do pacote pelo nome do seu workspace, substituindo pelo nome do respetivo package.json:

npm run test --workspace=@acme/math

Se o pacote utilizar um nome de script diferente, utilize esse nome. Se não tiver um script de teste, este comando não pode testar o seu comportamento; execute as verificações que o projeto realmente define, tais como os seus scripts de build ou lint. Evite confiar apenas num comando de teste ao nível da raiz: os comandos do npm, como o test, operam na raiz, a menos que selecione um workspace. npm Workspaces

2. Rever e criar o tarball do pacote

Um teste local no workspace não prova que os ficheiros de que os consumidores precisam estão incluídos no pacote. Primeiro, pré-visualize o conteúdo do pacote do workspace selecionado a partir da raiz do monorepo:

npm pack --workspace=@acme/math --dry-run

Reveja a lista de ficheiros quanto ao ponto de entrada do pacote, ficheiros compilados de saída, declarações de tipos e quaisquer outros ficheiros prometidos pelo pacote. As definições files, .npmignore e .gitignore do npm afetam os conteúdos; o package.json e os ficheiros README e de licença estão entre os que o npm inclui por predefinição. Verifique se main ou exports apontam para ficheiros que estarão no arquivo. npm pack, package.json files and entry points

Quando a lista parecer correta, crie um tarball real num diretório temporário. Os seguintes comandos utilizam a proteção de caracteres (quoting) compatível com zsh predefinida do macOS e mantêm o artefacto fora do seu repositório:

scratch="$(mktemp -d "${TMPDIR:-/tmp}/workspace-package-check.XXXXXX")"
npm pack --workspace=@acme/math --pack-destination="$scratch"

--dry-run apenas relata o que o npm empacotaria; não cria o arquivo. O segundo comando cria um, mas não faz o respetivo upload. A documentação do npm descreve o npm pack como criador de um tarball e reconhece o seletor de workspace. npm pack

3. Instalar o arquivo numa pasta limpa de consumidor

Encontre o caminho do tarball, crie um diretório de consumidor separado e instale aí o arquivo. Este exemplo pressupõe que apenas um tarball foi empacotado para o diretório temporário:

tarball="$(find "$scratch" -maxdepth 1 -name '*.tgz' -print -quit)"
consumer="$scratch/consumer"
mkdir -p "$consumer"
cd "$consumer"
npm init -y
npm install "$tarball"

Instalar um .tgz testa o artefacto empacotado. Instalar uma pasta de workspace ou utilizar a dependência ligada do monorepo pode ter comportamentos diferentes. npm install

Agora, experimente o pacote através do seu ponto de entrada público. Utilize o nome real do pacote e uma pequena verificação de consumidor adequada à sua API — por exemplo, faça require ou import do mesmo e, em seguida, chame uma função exportada representativa. Execute essa verificação a partir do diretório de consumidor, onde o pacote é resolvido a partir do node_modules recém-instalado. Se o projeto publicar código compilado, certifique-se de que a compilação (build) foi executada antes de empacotar; caso contrário, o arquivo poderá não ter ficheiros mesmo que os testes em tempo de desenvolvimento tenham passado.

4. Diagnosticar falhas antes de publicar

Se a instalação falhar, verifique se o arquivo tem um package.json com name e version, inspecione a sua lista de ficheiros e confirme que os pontos de entrada configurados existem no tarball. Se a importação falhar, compare o formato de módulo do consumidor com as definições type, main e exports do pacote. Um pacote pode passar nos testes do workspace e, mesmo assim, falhar aqui porque esses testes podem carregar ficheiros de código-fonte diretamente ou resolver dependências não declaradas a partir do monorepo.

Se uma dependência for outro workspace não publicado, teste também o esquema de lançamento pretendido. Um consumidor que instale um tarball não receberá automaticamente o código-fonte de um workspace irmão através da ligação do monorepo. Certifique-se de que os pacotes irmãos estão publicados/disponíveis em versões compatíveis, ou utilize uma configuração deliberadamente agregada (bundled) ou instalável. Este procedimento verifica um pacote empacotado localmente no ambiente Mac/Node atual; não consegue assegurar o comportamento em todas as versões do Node, sistemas operativos ou configurações de registo.

O ponto de paragem útil é um teste de workspace com sucesso, uma lista de ficheiros de pacote plausível e uma verificação de consumidor que instale e teste o tarball fora do monorepo. Mantenha o diretório temporário se precisar de o inspecionar, ou remova-o com rm -rf "$scratch" após confirmar que a variável ainda aponta para o caminho temporário gerado.

Fontes