Para instalar dependências para um único pacote em um projeto de workspace npm no macOS, execute npm install --workspace="packages/web" a partir da raiz do projeto, substituindo packages/web pelo caminho do workspace ou pelo nome do pacote. Você também pode acessar o diretório desse workspace e executar npm install. Esses comandos selecionam um workspace no projeto do npm; eles não criam um diretório de instalação separado nem garantem que apenas os arquivos daquele pacote serão alterados.

Verifique se o projeto é um workspace npm

Um workspace npm é um diretório de pacote listado no package.json raiz sob workspaces. Por exemplo, um repositório pode conter um package.json raiz e um packages/web/package.json, com "packages/*" na lista de workspaces da raiz. O npm usa essa configuração para reconhecer e vincular os pacotes locais. Se a pasta não estiver configurada como um workspace, o --workspace não poderá direcioná-la como tal. Consulte a documentação de workspaces do npm.

No Terminal, vá para a raiz do repositório. No macOS, coloque caminhos que contenham espaços entre aspas para que o shell trate o caminho como um único argumento:

cd "$HOME/Projects/sample monorepo"
npm install --workspace="packages/web"

Aqui, packages/web é um exemplo de caminho relativo à raiz do repositório. Em vez disso, você pode usar o nome do pacote de um workspace configurado, como npm install --workspace="@example/web". O npm documenta nomes de workspace, caminhos de diretórios de workspace e caminhos de workspace pai como seletores válidos. Dê preferência ao caminho ou nome específico do pacote: selecionar o diretório de um workspace pai pode selecionar todos os workspaces abaixo dele. As opções de npm install do npm descrevem o seletor.

Instale as dependências declaradas do workspace selecionado

O comando acima executa a instalação no contexto do workspace selecionado. Sem nenhum nome de pacote após install, o npm instala dependências já declaradas nos manifestos do projeto; ele não adiciona uma nova dependência ao packages/web/package.json. A configuração de workspaces do npm tem como padrão excluir o projeto raiz quando um workspace individual é selecionado, a menos que include-workspace-root esteja ativado. A referência de configuração do npm documenta ambas as opções.

Para um pacote que você deseja adicionar, inclua o nome dele antes do seletor de workspace:

npm install date-fns --workspace="packages/web"

Isso instrui o npm a adicionar date-fns às dependências daquele workspace e instalá-lo. Verifique o package.json do workspace depois para confirmar se a dependência foi gravada onde planejado. O guia de workspaces do npm apresenta o mesmo padrão para adicionar uma dependência a um workspace com nome especificado.

Use o diretório do workspace como alternativa

Se você já estiver trabalhando na pasta do pacote, pode executar npm install diretamente nela em vez de especificar --workspace:

cd "$HOME/Projects/sample monorepo/packages/web"
npm install

O npm documenta que executar um comando a partir de um workspace define implicitamente o contexto do workspace e usa a raiz do workspace como o prefixo do projeto. Isso pode ser conveniente em uma aba do terminal dedicada a um único pacote. Se não tiver certeza de a qual pacote o diretório atual pertence, use o comando explícito --workspace a partir da raiz conhecida do repositório.

Entenda o que “um único workspace” significa e não significa

Selecionar um workspace limita o contexto de workspace do comando; não promete uma árvore de node_modules fisicamente separada. Os workspaces do npm são gerenciados a partir de um projeto de nível superior, e o npm pode vincular workspaces locais ao diretório node_modules raiz. As dependências podem ser elevadas (hoisted) ou compartilhadas sempre que a árvore de dependências permitir. A instalação pode, portanto, afetar o estado de instalação compartilhado do repositório e o arquivo lockfile. Revise as alterações resultantes no controle de versão, especialmente se você esperava uma modificação no sistema de arquivos restrita apenas ao pacote. A documentação de instalação do npm explica o comportamento da árvore de dependências e a vinculação de workspaces.

Se o seu objetivo é uma instalação completamente independente e isolada do monorepo, o seletor de workspace não é o mecanismo adequado para isso. Um workspace faz parte do projeto raiz configurado; direcioná-lo não o transforma em um repositório ou árvore de instalação independente.

Se o npm não reconhecer o destino

Primeiro, verifique se o caminho está correto em relação à raiz do repositório e se o package.json dele existe. Em seguida, inspecione o package.json raiz e confirme se seus padrões em workspaces incluem essa pasta. Se estiver usando um nome, confirme se ele corresponde ao campo name do pacote do workspace. Execute o comando a partir da raiz do repositório ou navegue diretamente para o diretório do workspace desejado. Evite --workspaces quando quiser apenas um pacote: a opção no plural seleciona todos os workspaces configurados. A regra prática é simples: use --workspace="path" a partir da raiz quando quiser um destino explícito e verifique o manifesto e as alterações no repositório após o término do npm.

Fontes