uma ferramenta para gerenciar projetos JavaScript com vários pacotes.

• Sobre
• Introdução
• Como Funciona
• Resolução De Problemas
• Comandos
• Variados
• Lerna.json
• Flags

About

split up large codebases into separate independently versioned packages is extremely useful for code sharing. No entanto, fazer mudanças em muitos repositórios é confuso e difícil de rastrear, e testar em repositórios fica complicado muito rápido.

para resolver estes (e muitos outros) problemas, alguns projetos irão organizar suas codebases em repositórios multi-pacotes (às vezes chamados monorepos). Projetos como Babel, React, Angular, Ember, Meteor, Jest, e muitos outros desenvolvem todos os seus pacotes dentro de um único repositório.

Lerna é uma ferramenta que otimiza o fluxo de trabalho em torno da Gestão de repositórios multi-pacotes com git e npm.

Lerna também pode reduzir os requisitos de tempo e espaço para inúmeras cópias de pacotes em ambientes de desenvolvimento e construção – normalmente uma desvantagem de dividir um projeto em muitos pacotes NPM separados. Veja a documentação do guincho para mais detalhes.Como é um acordo Lerna?

há realmente muito pouco para ele. Você tem um sistema de arquivos que se parece com este:

my-lerna-repo/ package.json packages/ package-1/ package.json package-2/ package.json

o que pode Lerna fazer?

os dois comandos primários em Lerna são lerna bootstrap E lerna publish.

bootstrap ligará dependências no Acordo de recompra. publish ajudará a publicar quaisquer pacotes atualizados.As instruções abaixo são para Lerna 2.X. recomendamos usá-lo em vez de 1.x para um novo projeto Lerna. Verifique o wiki se você precisa ver o 1.X README.

vamos começar por instalar Lerna globalmente com npm.

$ npm install --global lerna

em seguida, vamos criar um novo repositório git:

$ git init lerna-repo$ cd lerna-repo

E agora vamos transformá-lo em um Lerna repo:

$ lerna init

O repositório deve agora olhar como este:

lerna-repo/ packages/ package.json lerna.json

Isto irá criar uma lerna.json arquivo de configuração, bem como um packages pasta.

como funciona

Lerna permite gerir o seu projecto utilizando um de dois modos: fixo ou independente.

modo fixo/bloqueado (por omissão)

modo fixo os projectos Lerna funcionam numa única linha de versão. A versão é mantida no arquivo lerna.json na raiz do seu projeto sob a chave version. Quando você executar lerna publish, se um módulo tiver sido atualizado desde a última vez que um lançamento foi feito, ele será atualizado para a nova versão que você está lançando. Isso significa que você só publica uma nova versão de um pacote quando você precisa.

este é o modo que o Babel está usando atualmente. Use isto se você quiser amarrar automaticamente todas as versões do pacote juntos. Um problema com esta abordagem é que uma grande mudança em qualquer pacote resultará em todos os pacotes ter uma nova versão maior.

modo independente (–independent)

modo independente projectos Lerna permite que os mantenedores incrementem versões de pacotes independentemente uns dos outros. Cada vez que você publicar, você receberá uma linha de comandos para cada pacote que foi alterado para especificar se é um patch, menor, maior ou alteração personalizada.

o modo independente permite que você atualize mais especificamente versões para cada pacote e faz sentido para um grupo de componentes. Combinar este modo com algo como semântica-release faria com que fosse menos doloroso. (Há trabalho sobre isso já no atlassian / lerna-semantic-release).

a chave version em lerna.json é ignorada no modo independente.

solução de problemas

se encontrar algum problema durante a utilização de Lerna, por favor verifique o nosso documento de solução de problemas, onde poderá encontrar a resposta para o seu problema.

perguntas mais frequentes

Consulte o FAQ.md.

Comandos

init

$ lerna init

Criar um novo Lerna de recompra ou atualizar um existente repo para a versão atual de Lerna.

Lerna assume que o Acordo de recompra já foi iniciado com git init.

quando executado, este comando:

1. adicione lerna como um devDependency em package.json se ainda não existir.
2. crie um ficheiro de configuração lerna.json para guardar o número version.

exemplo de saída num novo Acordo de reporte git:

$ lerna initlerna info version v2.0.0lerna info Updating package.jsonlerna info Creating lerna.jsonlerna success Initialized Lerna files

–independent, – I

$ lerna init --independent

This flag tells Lerna to use independent versioning mode.

— exact

$ lerna init --exact

por defeito, lerna init usará um intervalo caret ao adicionar ou actualizar a versão local de lerna, tal como npm install --save-dev lerna.

para manter o lerna 1.comportamento x de comparação” exata”, passar esta bandeira. Ele irá configurar lerna.json para forçar a correspondência exata para todas as execuções subsequentes.

{ "lerna": "2.0.0", "command": { "init": { "exact": true } }, "version": "0.0.0"}

bootstrap

$ lerna bootstrap

Bootstrap the packages in the current Lerna repo. Instala todas as suas dependências e liga todas as dependências cruzadas.

quando executado, este comando:

1. npm install todas as dependências externas de cada pacote.
2. Symlink together all Lerna packages that are dependencies of each other.
3. npm prepublish todos os pacotes de inicialização.

lerna bootstrap respeita as bandeiras --ignore, --scope e --include-filtered-dependencies (ver bandeiras).

Passar argumentos extras para a ngp cliente, colocando-os depois --:

$ lerna bootstrap -- --production --no-optional

também Pode ser configurado em lerna.json:

{ ... "npmClient": "yarn", "npmClientArgs": }

Como bootstrap funciona

Vamos usar babel como um exemplo.

• babel-generator e source-map (entre outros) são dependências de babel-core.
• babel-core‘s package.json lista ambos os pacotes como chaves em dependencies, como mostrado abaixo.

// babel-core package.json{ "name": "babel-core", ... "dependencies": { ... "babel-generator": "^6.9.0", ... "source-map": "^0.5.0" }}

• Lerna verifica se cada dependência é também parte do repo Lerna.
  • neste exemplo, babel-generator pode ser uma dependência interna, enquanto source-map é sempre uma dependência externa.
  • a versão de babel-generator no package.json de babel-core é satisfeita por packages/babel-generator, passando por uma dependência interna.
  • source-map é npm installed (ou yarned) como normal.
• packages/babel-core/node_modules/babel-generator links simbólicos para packages/babel-generator
• Isso permite que aninhadas importações de diretório

Notas:

• Quando uma dependência de versão de um pacote não está satisfeito por um pacote com o mesmo nome no acordo de recompra, será npm installed (ou yarned) como normal.
• Dest-tags, como latest, não satisfazem intervalos de semver.
• as dependências circulares resultam em ligações simbólicas circulares que podem afectar o seu editor/IDE.

o “Webstorm” bloqueia quando existem ligações simbólicas circulares. Para evitar isso, adicione node_modules à lista de arquivos e pastas ignorados em Preferences | Editor | File Types | Ignored files and folders.

publique

$ lerna publish

publique pacotes no projeto Lerna atual. Quando executado, este comando faz o seguinte:

cria um novo lançamento dos pacotes que foram atualizados. Pede uma nova versão. Cria um novo commit / tag git no processo de publicação para npm.Mais especificamente, este comando:

1. executar o equivalente a lerna updated para determinar quais pacotes precisam ser publicados.Se necessário, aumentar a tecla version em lerna.json.
2. atualize o package.json de todos os pacotes atualizados para suas novas versões.
3. actualize todas as dependências dos pacotes actualizados com as novas versões, especificadas com um caret (^).
4. crie um novo commit e tag git para a nova versão.
5. publique pacotes atualizados para npm.

Lerna não publicará pacotes marcados como privados ("private": true no package.json).

–exact

$ lerna publish --exact

quando executado com esta bandeira, publish irá especificar dependências actualizadas em pacotes actualizados exactamente (sem pontuação), em vez de como compatível com um semver (com um ^).Para mais informações, consulte a embalagem.documentação de dependências json.

–npm-tag

$ lerna publish --npm-tag=next

When run with this flag, publish will publish to npm with the given npm dist-tag (defaults to latest).Esta opção pode ser usada para publicar uma versão prerelease ou beta.

Nota: a etiqueta latest é a que é usada quando um usuário executa npm install my-package. Para instalar uma tag diferente,um usuário pode executar npm install [email protected].

–canary, – c

$ lerna publish --canary$ lerna publish --canary=beta

quando executado com esta bandeira, publish publica pacotes de uma forma mais granular (por commit). Antes de publicar para npm, ele cria a nova tag version, levando a atual version, empurrando-a para a próxima versão menor, adicionando o meta sufixo fornecido (por omissão alpha) e adicionando o Git sha atual (ex: 1.0.0 torna-se 1.1.0-alpha.81e3b443).

o caso de uso pretendido para esta bandeira é uma versão para o nível de commit ou para a liberação noturna.

–convencional-compromete-se

$ lerna publish --conventional-commits

Quando executado com essa bandeira, publish irá usar o Convencional Compromete-se a Especificação para determinar a versão colisão e gerar CHANGELOG

–git remoto

$ lerna publish --git-remote upstream

Quando executado com essa bandeira, publish vai empurrar o git alterações remoto especificado em vez de origin.

–skip-git

$ lerna publish --skip-git

When run with this flag, publish will publish to npm without running any of the git commands.

apenas publicar para o MPN; ignorar o compromisso, marcar e empurrar as alterações do git (isto só afecta a publicação).

–skip-npm

$ lerna publish --skip-npm

quando executado com esta bandeira, publish irá atualizar todas as versões de pacotes e dependências package.json, mas não irá realmente publicar os pacotes para npm.

isto foi útil como uma solução para um problema npm que foi entretanto corrigido. Ao publicar com README alterações, use --skip-npm e faça a final npm publish à mão para cada pacote.

esta bandeira pode ser combinada com --skip-git para apenas atualizar versões e dependências, sem cometer, marcar, empurrar ou publicar.

apenas actualize versões e dependências; não publique realmente (isto só afecta a publicação).

–force-publish

$ lerna publish --force-publish=package-2,package-4# force publish all packages$ lerna publish --force-publish=*

When run with this flag, publish will force publish the specified packages (comma-separated) or all packages using *.

isto irá ignorar a verificação de pacotes alterados e obriga a actualizar um pacote que não teve uma alteração git diff.

–sim

$ lerna publish --canary --yes# skips `Are you sure you want to publish the above changes?`

quando executado com esta bandeira, publish irá ignorar todas as mensagens de confirmação. Útil em integração contínua (IC) para responder automaticamente ao prompt de confirmação de publicação.

–cd-version

When run with this flag, publish will skip the version selection prompt (in independent mode) and use the next specified semantic version. Você ainda deve usar a bandeira --yes para evitar todas as indicações. Isto é útil quando os sistemas de compilação precisam de publicar sem instruções de comando. Funciona tanto em modos normais como independentes.

— pre-id

–repo-version

$ lerna publish --repo-version 1.0.1# applies version and skips `Select a new version for...` prompt

When run with this flag, publish will skip the version selection prompt and use the specified version. Útil para contornar a linha de entrada do utilizador se já souber qual a versão a publicar.

— message, – m

When run with this flag, publish will use the provided message when committing the version updates for publication. Útil para a integração de lerna em projetos que esperam que mensagens de commit adiram a certas diretrizes, tais como projetos que utilizam o commitizen e/ou semantic-release.

se a mensagem contiver %s, será substituída pelo novo número da versão global prefixado com um”v”. Note que isso só se aplica quando se usa o modo de versionamento “Fixo” Padrão, como não existe uma versão “global” quando se usa --independent.

updated

$ lerna updated

Check which packages have changed since the last release (the last git tag).

Lerna determina a última tag git criada e executa git diff --name-only v6.8.1 para alterar todos os arquivos desde essa tag. Ele então retorna um array de pacotes que têm um arquivo atualizado.

Note que a configuração para o comando publish também afeta o comando updated. Por exemplo config.publish.ignore

–json

$ lerna updated --json

Quando executado com essa bandeira, updated irá retornar um array de objetos no seguinte formato:

limpar

$ lerna clean

Remover node_modules diretório de todos os pacotes.

lerna clean respeita as bandeiras --ignore, --scope e --yes (ver bandeiras).

diff

$ lerna diff $ lerna diff# diff a specific package$ lerna diff package-name

Diff todas as embalagens ou uma única embalagem desde a última versão.

semelhante a lerna updated. Este comando é executado git diff.

ls

$ lerna ls

Liste todos os pacotes públicos no actual acordo Lerna.

lerna ls respeita as bandeiras --ignore e --scope (ver bandeiras).

–json

$ lerna ls --json

Quando executado com essa bandeira, ls irá retornar um array de objetos no seguinte formato:

executar

Executar uma npm script em cada pacote que contém o script. Um dash duplo (--) é necessário para passar argumentos tracejados para a execução do script.

lerna run respeita a --concurrency, --scope, --ignore, --stream, e --parallel bandeiras (ver bandeiras).

$ lerna run --scope my-component test

nota: é aconselhável restringir o âmbito deste comando (e lerna exec, abaixo) ao usar a bandeira --parallel, uma vez que a reprodução de dezenas de sub-processos pode ser prejudicial à equanimidade da sua shell (ou limite máximo de descritor de ficheiros, por exemplo). YMMV

exec

$ lerna exec -- <command> # runs the command in all packages$ lerna exec -- rm -rf ./node_modules$ lerna exec -- protractor conf.js

execute um comando arbitrário em cada pacote. Um Double-dash (--) é necessário para passar bandeiras tracejadas para o comando gerado, mas não é necessário quando todos os argumentos são posicionais.

lerna exec respeita a --concurrency, --scope, --ignore, e --parallel bandeiras (ver bandeiras).

$ lerna exec --scope my-component -- ls -la

Para gerar processos de longa execução, passar a --parallel bandeira:

# transpile all modules as they change in every package$ lerna exec --parallel -- babel src -d lib -w

Você também pode obter o nome do pacote atual, através da variável de ambiente LERNA_PACKAGE_NAME:

$ lerna exec -- npm view $LERNA_PACKAGE_NAME

Você também pode executar um script localizado no diretório raiz, em um complicado dir estrutura através da variável de ambiente LERNA_ROOT_PATH:

$ lerna exec -- node $LERNA_ROOT_PATH/scripts/some-script.js

Dica: Os comandos são gerados em paralelo, usando a simultaneidade dado (exceto com --parallel). A saída é canalizada, por isso não é determinística. Se você quiser executar o comando em um pacote após o outro, use-o assim:

$ lerna exec --concurrency 1 -- ls -la

–bail

$ lerna exec --bail=<boolean> <command>

esta bandeira significa se o comando exec deve ou não interromper a execução ao encontrar um erro lançado por um dos sub-processos desovados. Seu valor padrão é true.

importar

$ lerna import <path-to-external-repository>

importar a embalagem em <path-to-external-repository>, com histórico de commit, para packages/<directory-name>. Os autores originais de commit, datas e mensagens são preservados. Os Commits são aplicados ao ramo atual.

isto é útil para reunir pacotes autônomos pré-existentes em um repo Lerna. Cada commit é modificado para fazer alterações em relação ao diretório de pacotes. Assim, por exemplo, o commit que adicionou package.json irá adicionar packages/<directory-name>/package.json.

Misc

Lerna irá logar num ficheiro lerna-debug.log (o mesmo que npm-debug.log) quando encontra um erro a correr um comando.

Lerna também tem suporte para pacotes escopados.

correr lerna sem argumentos irá mostrar todos os comandos/opções.

lerna.json

{ "lerna": "2.0.0", "version": "1.1.3", "commands": { "publish": { "ignore": }, "bootstrap": { "ignore": "component-*" } }, "packages": }

• lerna: a versão atual de Lerna sendo usada.
• version: a versão atual do repositório.
• commands.publish.ignore: uma série de globos que não serão incluídos em lerna updated/publish. Use isso para evitar a publicação de uma nova versão desnecessariamente para alterações, como a fixação de um README.md typo.
• commands.bootstrap.ignore: um conjunto de globos que não serão activados ao executar o comando lerna bootstrap.
• commands.bootstrap.scope: uma lista de globs que restringe os pacotes que serão inicializados ao executar o comando lerna bootstrap.
• packages: uma série de globs para usar como localizações de pacotes.

dependências comuns

a maioria devDependencies pode ser puxada para a raiz de um acordo de Lerna.Isto tem alguns benefícios:

• Todos os pacotes de utilizar a mesma versão de um determinado dependência
• Pode manter dependências na raiz up-to-date com uma ferramenta automatizada, como GreenKeeper
• Dependência do tempo de instalação é reduzido
• Menos de armazenamento é necessário

Note que devDependencies fornecimento de “binário” executáveis que são usados pelo npm scripts ainda precisa ser instalado diretamente em cada pacote, onde eles são utilizados.

por exemplo, a dependência nsp é necessária neste caso para que lerna run nsp (e npm run nsp dentro do diretório do pacote) funcione corretamente.:

{ "scripts": { "nsp": "nsp" }, "devDependencies": { "nsp": "^2.3.3" }}

Flags

opções para Lerna pode vir de configuração (lerna.json) ou na linha de comando. Além disso, as opções na configuração podem viver no nível superior ou podem ser aplicadas a comandos específicos.

Exemplo:

{ "lerna": "x.x.x", "version": "1.2.0", "exampleOption": "foo", "command": { "init": { "exampleOption": "bar", } },}

neste caso exampleOption será “foo” para todos os comandos, exceto init, onde será o “bar”. Em todos os casos pode ser substituído por “baz”na linha de comando com --example-option=baz.

–concurrency

quantos fios usar quando Lerna paralisa as tarefas (por omissão:4)

$ lerna publish --concurrency 1

— escopo

Escopo um comando para um subconjunto de pacotes.

$ lerna exec --scope my-component -- ls -la

$ lerna run --scope toolbar-* test

–desde

ao executar um script ou Comando, escopo a operação para pacotes que foram atualizados desde o especificado ref. Se ref não for especificado, o valor por omissão corresponde à última etiqueta.

liste o conteúdo das embalagens que mudaram desde a última etiqueta:

$ lerna exec --since -- ls -la

execute os testes para todos os pacotes que foram alterados desde master:

$ lerna run test --since master

listar todos os pacotes que mudaram desde então some-branch:

$ lerna ls --since some-branch

isto pode ser particularmente útil quando usado em IC, se você pode obter o ramo alvo em que um PR irá entrar, porque você pode usar isso como a opção ref para --since. Isto funciona bem para PRs indo para master, bem como ramos de recursos.

— ignore

exclui um subconjunto de pacotes ao executar um comando.

$ lerna bootstrap --ignore component-*

a bandeira ignore, quando usada com o comando bootstrap, também pode ser definida em lerna.json sob a chave commands.bootstrap. A bandeira da linha de comandos irá tomar a precendência sobre esta opção.Exemplo

{ "lerna": "2.0.0", "version": "0.0.0", "commands": { "bootstrap": { "ignore": "component-*" } }}

dica: a glob é igualada com o nome do pacote definido em package.json, não com o nome de diretório em que o pacote vive.

–incluem-dependências filtradas

Nota: Isto irá sobrepor as bandeiras --scope e --ignore.

isto é, um pacote acompanhado pela bandeira --ignore ainda será inicializado se depender de outro pacote que está sendo inicializado.

isto é útil para situações em que você quer “configurar” um único pacote que depende de outros pacotes sendo configurados.

$ lerna bootstrap --scope my-component --include-filtered-dependencies# my-component and all of its dependencies will be bootstrapped

–loglevel

qual o nível de logs a reportar. Em caso de falha, todos os logs são escritos em Lerna-debug.registar na pasta de trabalho actual.

quaisquer Toros de um nível mais elevado do que a configuração são mostrados. O padrão é “info”.

— Max-buffer

Set a max buffer length for each underlying process call. Útil, por exemplo, quando alguém quer importar um acordo de recompra com uma quantidade maior de commits ao executar lerna import. Nesse caso, o comprimento do tampão incorporado pode não ser suficiente.

–no-sort

por padrão, todas as tarefas executam em pacotes em ordem topologicamente ordenada a respeito das relações de dependência dos pacotes em questão. Os ciclos são quebrados em uma base de melhor esforço de uma forma não garantida para ser consistente em todas as invocações de Lerna.

a ordenação topológica pode causar estrangulamentos de concorrência se houver um pequeno número de pacotes com muitos dependentes ou se alguns pacotes levam um tempo desproporcionalmente longo para serem executados. A opção --no-sort desactiva a ordenação, em vez de executar tarefas em uma ordem arbitrária com a concorrência máxima.

esta opção também pode ajudar se executar vários comandos de “vigia”. Uma vez que lerna run irá executar comandos em ordem topologicamente ordenada, pode acabar à espera de um comando antes de seguir em frente. Isto irá bloquear a execução quando você executar comandos “watch”, uma vez que eles normalmente nunca terminam. Um exemplo de um comando de” Vigia ” está a correr babel com a bandeira CLI --watch.

–hoist

instale dependências externas correspondentes a glob na raiz do repo, de modo que estejam disponíveis para todos os pacotes. Quaisquer binários dessas dependências serão ligados em pacotes dependentes node_modules/.bin/ diretórios para que eles estejam disponíveis para scripts npm. Se a opção está presente, mas não glob é dado o padrão é ** (içar tudo). Esta opção só afecta o comando bootstrap.

$ lerna bootstrap --hoist

para informação geral sobre --hoist, ver a documentação do guincho.

Nota: Se os pacotes dependem de diferentes versões de uma dependência externa, a versão mais comumente usada será içada, e um aviso será emitido.

–nohoist

não instale dependências externas correspondentes a glob na raiz do Acordo de recompra. Isto pode ser usado para optar por não içar para certas dependências.

$ lerna bootstrap --hoist --nohoist=babel-*

–npm-client

Install external dependencies using install. Deve ser um executável que saiba como instalar dependências npm.

$ lerna bootstrap --npm-client=yarn

também pode ser configurado em lerna.json:

{ ... "npmClient": "yarn"}

–use-espaços de trabalho

permite a integração com espaços de trabalho de fios (disponível desde [email protected]+).
os valores no array são os comandos em que Lerna irá delegar operação ao fio (atualmente apenas bootstrapping).
Se --use-workspaces é verdade, então packages deverá ser substituída pelo valor de package.json/workspaces.
também Pode ser configurado em lerna.json:

{ ... "npmClient": "yarn", "useWorkspaces": true}

–stream

saída de Fluxo de processos filho imediatamente, com prefixo de origem nome do pacote. Isto permite que a saída de diferentes pacotes seja intercalada.

$ lerna run watch --stream

–paralela

semelhante a --stream, mas completamente desconsiderada a concorrência e a ordenação topológica, executando um determinado comando ou programa imediatamente em todos os pacotes correspondentes com saída de streaming prefixada. Esta é a bandeira preferida para processos de longa duração, tais como babel src -d lib -w executar sobre muitos pacotes.

$ lerna exec --parallel -- babel src -d lib -w

–registro

quando executado com esta bandeira, comandos npm encaminhados irão usar o registro especificado para o(s) Seu (s) Pacote (s).

isto é útil se não quiser configurar explicitamente a configuração do seu registo em todo o seu pacote.ficheiros json individualmente quando, por exemplo, utilizam registos privados.

— temp-tag

quando for aprovada, esta opção irá alterar o processo de publicação por omissão, publicando primeiro todos os pacotes alterados para uma dist-tag temporária (lerna-temp) e, em seguida, movendo a (s) Nova (S) Versão (s) para a dist-tag por omissão (latest).

isto não é geralmente necessário, pois Lerna irá publicar pacotes em ordem topológica (todas as dependências antes dos dependentes) por padrão.

Wizard

se preferir alguma orientação para cli (no caso de estar prestes a começar a usar lerna ou a apresentá-la a uma nova equipa), poderá gostar de Lerna-wizard. Irá conduzi-lo através de uma série de passos bem definidos:

marcas actuais