It is a tool for controlling multiple projects (called packages in laoban
-speak). While it is fairly language agnostic it
probably offers the most value to javascript/typescript projects in a monorepo.
- If you are new to a package that is managed by
laoban
then start here - If you want to try out
laoban
on your package start here
If you have tried to use lerna
or yarn workspaces
and found them lacking then this might be for you.
It is useful if you want to have a typescript project made of small chunks of code (a main + libraries) or want to control and manage dependencies / tech stack at 'the team level' or 'the organisation level'
- Easy to have scripts execute in multiple packages simultaneously
- Scripts execute in the 'right order' if there are dependencies between packages. (for example compilation needs the dependencies to be compiled first)
- With 'guards' as some scripts aren't suitable for all packages
- Maintains a 'status' across all packages, so that you can see which packages have not compiled, tested or published successfully
- Excellent logging of the scripts (you can easily find the log for 'this command' executed at 'this time' in 'this package')
- Easy to update version numbers across packages
- Easy to publish all packages in a single command
- If many of your packages use a dependency and you want to update that dependency you can do it in one place
- If you have configuration files like jest.config, tsconfig.json, tslint.json, etc. you can manage them in one place
- Easy to make your own 'templates' (often trivially easy)
- Templates extend other templates, so you can have a 'base' template and then extend it with 'just the differences'
- Different package types need different groups of scripts.
- For example some packages need to be compiled, others don't.
- Some packages need gui testing, others don't.
- Some packages are java based and use maven, others are typescript based and need yarn or npm commands
- We want to be able to manage these scripts centrally as an organisation, but allow individual packages to override them
- If you are a single developer with a single small javascript/typescript project there is no value in using laoban
- If you are working on a project and maintaining libraries, or have split the project into multiple packages then laoban can help you manage them
- If you are developing a large project that is big and ungainly, and you would like to split it up, but 'it's too hard' then laoban is ideal to help you
- If you are a member of a company with standards (such as 'which version of node', 'which version of react') then laoban is ideal to help you manage those standards
npm
does not handle multiple packages well. Each package is a separate package.json that is managed separately. There
is no ability to 'inherit' or share configuration, so in a package with many moving parts each of which is implemented
with a small bit of javascript/typescript, it can be difficult to keep all the dependencies in line.
In the past I have found myself making a whole raft of scripts, and then forgetting which one was which / how they worked
/ how to modify them. Copying them for use in other packages was problematic and prone to error. Most of the logic in the
script was the same, and can be generalised across multiple packages. laoban
is the result of
refactoring these scripts and making them more declarative.
Laoban is not very opinionated about which one to use. Replacing npm
with yarn
in the config will let you use all the features with yarn. If
you want to use it with maven or sbt or... it works fine (although those other language tools already have much of the capabilities
that laoban brings to the javascript world). By 'not very opinionated' we mean
'you should be using yarn workspaces in a monorepo world, but if you don't want to you can use npm... but your
life will be much harder'
- Running all the tests in parallel across multiple packages
- Without this I have to manually run them one at a time or make a script to call them (which is error-prone and usually without parallelism)
- Seeing the status of the important commands
- Which packages have not compiled, or tested, or published successfully?
- And then go and look at only the 'important' log and find why
- When working with ten or more packages I found it very hard to get a simple of view of how well the code was behaving in each package
- Which packages have not compiled, or tested, or published successfully?
- Updating all the 'react' package settings in one go
- You can update the template settings, then call
laoban update
- You can compile the changes in one command
laoban compile
- You can test the changes in one command
laoban test
- And now you can get a status of all the packages, knowing which have been impacted negatively with
laoban status
- You can update the template settings, then call
- Updating a global version number
- If the packages are tightly coupled, I like them to share a version number.
- I can update them all with one command
laoban update --minor
orlaoban update --major
-
git clone
the project -
yarn
to download all the dependencies -
laoban compile
will compile the packages in the correct order -
laoban test
will test the packages -
laoban status
will let you see which packages compiled and passed all their tests
-
laoban update --minor
will update all the packages to the new minor version number (or you can use--major
or--setVersion xxx
) -
laoban publish
will publish all the packages
I tried every 'boss' or 'controller' word I could think of! Laoban is Chinese for 'boss' and wasn't taken on npmjs (although it was on github)