ett verktyg för att hantera JavaScript-projekt med flera paket.

• Om
• Komma Igång
• Hur Det Fungerar
• Felsökning
• Kommandon
• Övrigt
• Lerna.json
• flaggor

om

att dela upp stora kodbaser i separata oberoende versionerade paket är extremt användbart för koddelning. Att göra ändringar i många repositorier är dock rörigt och svårt att spåra, och testning över repositorier blir komplicerat riktigt snabbt.

för att lösa dessa (och många andra) problem kommer vissa projekt att organisera sina kodbaser i flera paketförvar (ibland kallade monorepos). Projekt som Babel, React, Angular, Ember, Meteor, Jest och många andra utvecklar alla sina paket inom ett enda arkiv.

Lerna är ett verktyg som optimerar arbetsflödet kring hantering av flera paketförvar med git och npm.

Lerna kan också minska tids – och rymdkraven för många kopior av paket i utvecklings-och byggmiljöer-normalt en nackdel med att dela ett projekt i många separata npm-paket. Se hissdokumentationen för mer information.

Hur ser en Lerna repo ut?

det finns faktiskt väldigt lite till det. Du har ett filsystem som ser ut så här:

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

vad kan Lerna göra?

de två primära kommandona i Lerna är lerna bootstrap och lerna publish.

bootstrap kommer att länka beroenden i repo tillsammans. publish hjälper till att publicera uppdaterade paket.

komma igång

instruktionerna nedan är för Lerna 2.x. Vi rekommenderar att du använder den istället för 1.x för ett nytt Lerna-projekt. Kontrollera wiki Om du behöver se 1.x README.

låt oss börja med att installera Lerna globalt med npm.

$ npm install --global lerna

nästa skapar vi ett nytt git-arkiv:

$ git init lerna-repo$ cd lerna-repo

och nu ska vi göra det till en Lerna repo:

$ lerna init

ditt förråd ska nu se ut så här:

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

detta skapar en lerna.json konfigurationsfil samt en packages mapp.

hur det fungerar

Lerna låter dig hantera ditt projekt med ett av två lägen: fast eller oberoende.

fast/låst läge (standard)

fast läge Lerna projekt fungerar på en enda version linje. Versionen lagras i lerna.json – filen i roten till ditt projekt under version – tangenten. När du kör lerna publish, om en modul har uppdaterats sedan förra gången en release gjordes, kommer den att uppdateras till den nya versionen du släpper. Det innebär att du bara publicerar en ny version av ett paket när du behöver.

Detta är det läge som Babel för närvarande använder. Använd detta om du automatiskt vill koppla samman alla paketversioner. Ett problem med detta tillvägagångssätt är att en stor förändring i något paket kommer att resultera i att alla paket har en ny huvudversion.

oberoende läge (–independent)

oberoende läge Lerna projects tillåter utvecklare att öka paketversioner oberoende av varandra. Varje gång du publicerar får du en fråga för varje paket som har ändrats för att ange om det är en korrigeringsfil, mindre, större eller anpassad ändring.

oberoende läge låter dig mer specifikt uppdatera versioner för varje paket och är vettigt för en grupp komponenter. Att kombinera detta läge med något som semantisk frisättning skulle göra det mindre smärtsamt. (Det finns arbete med detta redan på atlassian / lerna-semantic-release).

version – tangenten i lerna.json ignoreras i oberoende läge.

felsökning

om du stöter på några problem när du använder Lerna, kolla in vårt Felsökningsdokument där du kan hitta svaret på ditt problem.

Vanliga frågor

se FAQ.md.

kommandon

init

$ lerna init

skapa en ny Lerna repo eller uppgradera en befintlig repo till den aktuella versionen av Lerna.

Lerna antar att repo redan har initierats med git init.

när det körs kommer detta kommando att:

1. Lägg till lerna som devDependency i package.json om det inte redan finns.
2. skapa en lerna.json konfigurationsfil för att lagra version – numret.

exempel på en ny git repo:

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

–independent, – i

$ lerna init --independent

denna flagga talar om för Lerna att använda oberoende versionshanteringsläge.

–exact

$ lerna init --exact

som standard kommer lerna init att använda ett caret-intervall när du lägger till eller uppdaterar den lokala versionen av lerna, precis som npm install --save-dev lerna.

för att behålla lerna 1.X beteende ”exakt” jämförelse, passera denna flagga. Det kommer att konfigurera lerna.json för att genomdriva exakt matchning för alla efterföljande avrättningar.

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

bootstrap

$ lerna bootstrap

Bootstrap paketen i den aktuella lerna repo. Installerar alla deras beroenden och länkar eventuella korsberoende.

när det körs kommer detta kommando att:

1. npm install alla externa beroenden för varje paket.
2. symboliska länkar samman alla Lerna packages som är beroende av varandra.
3. npm prepublish alla bootstrapped paket.

lerna bootstrap respekterar flaggorna --ignore, --scope och --include-filtered-dependencies (se flaggor).

skicka extra argument till npm-klienten genom att placera dem efter --:

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

kan också konfigureras i lerna.json:

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

hur bootstrap fungerar

Låt oss använda babel som ett exempel.

• babel-generator och source-map(bland andra) är beroenden av babel-core.
• babel-core’s package.json listar båda dessa paket som nycklar i dependencies, som visas nedan.

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

• Lerna kontrollerar om varje beroende också är en del av lerna repo.
  • i det här exemplet kan babel-generator vara ett internt beroende, medan source-map alltid är ett externt beroende.
  • versionen av babel-generator i package.json av babel-core är nöjd med packages/babel-generator och passerar för ett internt beroende.
  • source-map är npm installed (eller yarned) som normalt.
• packages/babel-core/node_modules/babel-generator symboliska länkar till packages/babel-generator
• detta tillåter kapslade katalog import

anteckningar:

• när en beroendeversion i ett paket inte uppfylls av ett paket med samma namn i repo kommer det att vara npm installed (eller yarned) som vanligt.
• Dist-taggar, som latest, uppfyller inte semver-intervall.
• cirkulära beroenden resulterar i cirkulära symboliska länkar som kan påverka din editor/IDE.

Webstorm låses upp när cirkulära symboliska länkar finns. För att förhindra detta, lägg till node_modulesi listan över ignorerade filer och mappar i Preferences | Editor | File Types | Ignored files and folders.

publicera

$ lerna publish

publicera paket i det aktuella Lerna-projektet. När det körs gör det här kommandot följande:

skapar en ny version av de paket som har uppdaterats. Frågar efter en ny version. Skapar en ny git commit / tag i processen att publicera till npm.

mer specifikt kommer detta kommando att:

1. kör motsvarande lerna updated för att avgöra vilka paket som behöver publiceras.
2. öka vid behov version – tangenten i lerna.json.
3. uppdatera package.json av alla uppdaterade paket till sina nya versioner.
4. uppdatera alla beroenden för de uppdaterade paketen med de nya versionerna, specificerade med en caret (^).
5. skapa en ny git commit och tagg för den nya versionen.
6. publicera uppdaterade paket till npm.

Lerna publicerar inte paket som är markerade som privata ("private": true i package.json).

–exakt

$ lerna publish --exact

när den körs med denna flagga, publish kommer att ange uppdaterade beroenden i uppdaterade paket exakt (utan skiljetecken), i stället för som semver kompatibel (med en ^).

för mer information, se paketet.JSON beroenden dokumentation.

–npm-tagg

$ lerna publish --npm-tag=next

när den körs med denna flagga, publish kommer att publicera till npm med den givna npm dist-tagg (standard latest).

det här alternativet kan användas för att publicera en prerelease eller beta version.

notera: taggen latest är den som används när en användare kör npm install my-package. För att installera en annan tagg kan en användare köra npm install [email protected].

–canary, – c

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

när den körs med denna flagga publicerar publish paket på ett mer detaljerat sätt (per commit). Innan den publiceras till npm skapar den den nya version – taggen genom att ta den aktuella version, stöta den till nästa mindre version, lägga till det medföljande meta-suffixet (som standard alpha) och lägga till den aktuella git sha (ex: 1.0.0 blir 1.1.0-alpha.81e3b443).

det avsedda användningsfallet för denna flagga är en per commit level release eller nightly release.

–konventionell-begår

$ lerna publish --conventional-commits

när den körs med denna flagga, publish kommer att använda den konventionella begår specifikationen för att bestämma version bump och generera CHANGELOG

–git-remote

$ lerna publish --git-remote upstream

när den körs med denna flagga, publish kommer att driva git ändringar till den angivna fjärrkontrollen i stället för origin.

–skip-git

$ lerna publish --skip-git

när den körs med denna flagga kommer publish att publicera till npm utan att köra någon av git-kommandona.

publicera bara till npm; hoppa över att begå, tagga och trycka på GIT-ändringar (detta påverkar bara publicera).

–skip-npm

$ lerna publish --skip-npm

när den körs med den här flaggan kommer publish att uppdatera alla package.json paketversioner och beroendeversioner, men det kommer inte att publicera paketen till npm.

detta var användbart som en lösning för ett npm-problem som sedan har åtgärdats. När du publicerar med README-ändringar, använd --skip-npm och gör den slutliga npm publish för hand för varje paket.

denna flagga kan kombineras med --skip-git för att bara uppdatera versioner och beroenden, utan att begå, märka, trycka eller publicera.

endast uppdatera versioner och beroenden; inte faktiskt publicera (detta påverkar bara publicera).

–force-publish

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

när den körs med denna flagga kommer publish att tvinga publicera de angivna paketen (kommaseparerade) eller alla paket med *.

detta hoppar över lerna updated – kontrollen för ändrade paket och tvingar ett paket som inte hade en git diff – ändring att uppdateras.

–ja

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

när den körs med den här flaggan hoppar publish över alla bekräftelsesmeddelanden. Användbar i Continuous integration (CI)för att automatiskt svara på publiceringsbekräftelsen.

–cd-version

när den körs med denna flagga hoppar publish över versionsvalsprompten (i oberoende läge) och använder nästa angivna semantiska version. Du måste fortfarande använda flaggan --yes för att undvika alla uppmaningar. Detta är användbart när byggsystem behöver publicera utan kommandotolkar. Fungerar i både normala och oberoende lägen.

–pre-id

–repo-version

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

när den körs med den här flaggan hoppar publish över versionsvalsprompten och använder den angivna versionen. Användbart för att kringgå användarinmatningsprompten om du redan vet vilken version du ska publicera.

–message, -m

när det körs med den här flaggan kommer publish att använda det medföljande meddelandet när versionsuppdateringarna görs för publicering. Användbar för att integrera lerna i projekt som förväntar sig att commit-meddelanden följer vissa riktlinjer, till exempel projekt som använder commitizen och/eller semantic-release.

om meddelandet innehåller %s kommer det att ersättas med det nya globala versionsnumret prefixet med ett ”v”. Observera att detta endast gäller när du använder standardversionen ”fast”, eftersom det inte finns någon ”global” version när du använder --independent.

uppdaterad

$ lerna updated

kontrollera vilka packages som har ändrats sedan den senaste utgåvan (den sista git-taggen).

Lerna bestämmer den senaste git-taggen som skapats och körs git diff --name-only v6.8.1 för att få alla filer ändrade sedan den taggen. Den returnerar sedan en rad paket som har en uppdaterad fil.

Observera att konfigurationen för kommandot publish också påverkar kommandot updated. Till exempel config.publish.ignore

–json

$ lerna updated --json

när den körs med den här flaggan returnerar updated en rad objekt i följande format:

rengör

$ lerna clean

ta bort katalogen node_modules från alla paket.

lerna clean respekterar flaggorna --ignore, --scope och --yes (se flaggor).

diff

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

Diff alla paket eller ett enda paket sedan den senaste utgåvan.

liknande lerna updated. Detta kommando körs git diff.

ls

$ lerna ls

lista alla publika paket i den aktuella lerna repo.

lerna ls respekterar flaggorna --ignore och --scope (se flaggor).

–json

$ lerna ls --json

när den körs med den här flaggan returnerar ls en rad objekt i följande format:

kör

kör ett npm-skript i varje paket som innehåller det skriptet. Ett dubbelstreck (--) är nödvändigt för att skicka streckade argument till skriptexekveringen.

lerna run respekterar --concurrency, --scope, --ignore, --stream, och --parallel flaggor (se flaggor).

$ lerna run --scope my-component test

Obs: Det rekommenderas att begränsa omfattningen av detta kommando (och lerna exec, nedan) när du använder --parallel flagga, som Lek dussintals delprocesser kan vara skadligt för skalets jämnmod (eller maximal fil deskriptor gräns, till exempel). YMMV

exec

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

kör ett godtyckligt kommando i varje paket. En dubbelstreck (--) är nödvändig för att skicka streckade flaggor till det skapade kommandot, men är inte nödvändigt när alla argument är positionella.

lerna exec respekterar --concurrency, --scope, --ignore, och --parallel flaggor (se flaggor).

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

för att skapa långvariga processer, passera flaggan --parallel :

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

du kan också få namnet på det aktuella paketet via miljövariabeln LERNA_PACKAGE_NAME:

$ lerna exec -- npm view $LERNA_PACKAGE_NAME

du kan också köra ett skript som finns i rotdir, i en komplicerad dir-struktur genom miljövariabeln LERNA_ROOT_PATH:

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

tips: kommandona skapas parallellt med den givna samtidigheten (utom med --parallel). Utgången leds genom, så inte deterministisk. Om du vill köra kommandot i ett paket efter det andra, använd det så här:

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

–bail

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

denna flagga betyder huruvida kommandot exec ska stoppa utförandet när det stöter på ett fel som kastas av en av de skapade delprocesserna. Dess standardvärde är true.

importera

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

importera paketet på <path-to-external-repository>, med commit history, till packages/<directory-name>. Ursprungliga begå författare, datum och meddelanden bevaras. Åtaganden tillämpas på den aktuella filialen.

detta är användbart för att samla befintliga fristående paket i en Lerna repo. Varje commit ändras för att göra ändringar i förhållande till paketkatalogen. Så, till exempel, commit som lagt till package.json kommer istället att lägga till packages/<directory-name>/package.json.

Misc

Lerna loggar till en lerna-debug.log – fil (samma som npm-debug.log) när det stöter på ett fel som kör ett kommando.

Lerna har också stöd för scoped paket.

Running lerna utan argument visar alla kommandon/alternativ.

lerna.json

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

• lerna: den nuvarande versionen av Lerna används.
• version: den nuvarande versionen av förvaret.
• commands.publish.ignore: en rad globs som inte kommer att ingå i lerna updated/publish. Använd detta för att förhindra att en ny version publiceras onödigt för ändringar, till exempel att fixa ett README.md skrivfel.
• commands.bootstrap.ignore: en rad globs som inte kommer att bootstrapped när du kör kommandot lerna bootstrap.
• commands.bootstrap.scope: en rad globs som begränsar vilka paket som ska startas när kommandot lerna bootstrap körs.
• packages: Array av globs att använda som paketplatser.

vanliga devDependencies

de flesta devDependencies kan dras upp till roten av en Lerna repo.

detta har några fördelar:

• alla paket använder samma version av ett givet beroende
• kan hålla beroenden vid roten uppdaterade med ett automatiserat verktyg som GreenKeeper
• Beroendeinstallationstiden reduceras
• mindre lagring behövs

Observera att devDependencies tillhandahåller ”binära” körbara filer som kan användas för att används av NPM-skript måste fortfarande installeras direkt i varje paket där de används.

till exempel är nsp – beroendet nödvändigt i detta fall för att lerna run nsp(och npm run nsp i paketets katalog) ska fungera korrekt:

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

flaggor

alternativ till Lerna kan komma från konfiguration (lerna.json) eller på kommandoraden. Dessutom alternativ i config kan leva på den översta nivån eller kan tillämpas på specifika kommandon.

exempel:

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

i det här fallet kommer exampleOption att vara ” foo ”för alla kommandon utom init, där det kommer att vara”bar”. I alla fall kan det åsidosättas till ” baz ” på kommandoraden med --example-option=baz.

–samtidighet

hur många trådar som ska användas när Lerna parallelliserar uppgifterna (standard 4)

$ lerna publish --concurrency 1

–scope

Scopes ett kommando till en delmängd av paket.

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

$ lerna run --scope toolbar-* test

–eftersom

när du kör ett skript eller kommando, omfattning åtgärden till paket som har uppdaterats sedan den angivna ref. Om ref inte anges, är den standard för den senaste taggen.

lista innehållet i paket som har ändrats sedan den senaste taggen:

$ lerna exec --since -- ls -la

kör testerna för alla paket som har ändrats sedan master:

$ lerna run test --since master

lista alla paket som har ändrats sedan some-branch:

$ lerna ls --since some-branch

detta kan vara särskilt användbart när det används i CI, om du kan få målgrenen kommer en PR att gå in, eftersom du kan använda det som ref till alternativet --since. Detta fungerar bra för PRs som går in i master såväl som funktionsgrenar.

–ignore

utesluter en delmängd av paket när ett kommando körs.

$ lerna bootstrap --ignore component-*

ignore flaggan, när den används med kommandot bootstrap, kan också ställas in i lerna.json under commands.bootstrap – tangenten. Kommandoradsflaggan kommer att ta föregång över det här alternativet.

exempel

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

tips: glob matchas mot paketnamnet definierat i package.json, inte katalognamnet paketet bor i.

–include-filtered-dependencies

Obs: Detta kommer att åsidosätta flaggorna --scope och --ignore.

dvs ett paket som matchas av flaggan --ignore kommer fortfarande att startas om det beror på ett annat paket som startas.

detta är användbart för situationer där du vill ”konfigurera” ett enda paket som bygger på att andra paket ställs in.

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

–loglevel

vilken nivå av loggar att rapportera. Vid fel skrivs alla loggar till lerna-debug.logga in i den aktuella arbetskatalogen.

alla loggar på en högre nivå än inställningen visas. Standardvärdet är ”info”.

–max-buffer

ange en maximal buffertlängd för varje underliggande processanrop. Användbart till exempel när någon vill importera en repo med en större mängd åtaganden medan du kör lerna import. I så fall kanske den inbyggda buffertlängden inte är tillräcklig.

–no-sort

som standard utförs alla uppgifter på paket i topologiskt sorterad ordning för att respektera beroendeförhållandena för de aktuella paketen. Cyklerna bryts på bästa sätt på ett sätt som inte garanteras vara konsekventa över Lerna-anrop.

topologisk sortering kan orsaka flaskhalsar i samtidighet om det finns ett litet antal paket med många beroende eller om vissa paket tar oproportionerligt lång tid att utföra. Alternativet --no-sort inaktiverar sortering och utför istället uppgifter i godtycklig ordning med maximal samtidighet.

det här alternativet kan också hjälpa om du kör flera” watch ” – kommandon. Eftersom lerna run kommer att utföra kommandon i topologiskt sorterad ordning kan det sluta vänta på ett kommando innan du går vidare. Detta blockerar körning när du kör ”watch” – kommandon, eftersom de vanligtvis aldrig slutar. Ett exempel på ett” watch ” – kommando körs babel med --watch CLI-flaggan.

–hoist

installera externa beroenden som matchar glob vid repo-roten så att de är tillgängliga för alla paket. Alla binärer från dessa beroenden kommer att länkas till beroende paket node_modules/.bin/ kataloger så att de är tillgängliga för npm-skript. Om alternativet är närvarande men ingen glob ges är standard ** (hissa allt). Det här alternativet påverkar bara kommandot bootstrap.

$ lerna bootstrap --hoist

för bakgrund på --hoist, se hissdokumentationen.

Obs: Om paket är beroende av olika versioner av ett externt beroende, kommer den vanligaste versionen hissas, och en varning kommer att avges.

–nohoist

installera inte externa beroenden som matchar glob vid repo-roten. Detta kan användas för att välja bort lyft för vissa beroenden.

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

–npm-klient

installera externa beroenden med install. Måste vara en körbar som vet hur man installerar npm-beroenden.

$ lerna bootstrap --npm-client=yarn

kan också konfigureras i lerna.json:

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

–användning-arbetsytor

möjliggör integration med Garnarbetsytor (tillgängliga sedan [email protected]+).
värdena i arrayen är de kommandon där Lerna kommer att delegera operation till garn (för närvarande endast bootstrapping).
om --use-workspaces är sant kommer packages att åsidosättas av värdet från package.json/workspaces.
kan också konfigureras i lerna.json:

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

–strömma

strömma utdata från underordnade processer omedelbart, prefixet med det ursprungliga paketnamnet. Detta gör att utdata från olika paket kan interfolieras.

$ lerna run watch --stream

–parallell

liknar --stream, men bortser helt från samtidighet och topologisk sortering, kör ett givet kommando eller skript omedelbart i alla matchande paket med prefixad strömningsutgång. Detta är den föredragna flaggan för långvariga processer som babel src -d lib -w körs över många paket.

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

–registry

när den körs med denna flagga, vidarebefordrade npm kommandon kommer att använda den angivna registret för ditt paket(s).

detta är användbart om du inte uttryckligen vill ställa in din registerkonfiguration i hela ditt paket.json filer individuellt när t.ex. med hjälp av privata register.

–temp-tag

när den passeras kommer denna flagga att ändra standardpubliceringsprocessen genom att först publicera alla ändrade paket till en tillfällig dist-tagg (lerna-temp) och sedan flytta den nya versionen till standard dist-taggen (latest).

detta är i allmänhet inte nödvändigt, eftersom Lerna publicerar paket i topologisk ordning (alla beroenden före beroende) som standard.

Wizard

om du föredrar lite vägledning för cli (om du ska börja använda lerna eller introducera det till ett nytt lag) kanske du gillar lerna-wizard. Det leder dig genom en serie väldefinierade steg:

nuvarande Taggar