BlueLibs is a lerna monorepo of TypeScript packages, not one framework

The unit of adoption is the package, not the ecosystem

BlueLibs describes itself as a collection of open-source products that help you quickly prototype web applications and scale your app while respecting SOLID principles. The word collection is the accurate one. There is no single BlueLibs framework you install and extend; there is a set of packages, and you take the ones you want.

The feature list makes that concrete. Dependency injection and module management sit in the core package. On top of that sits a database agnostic security system, a server agnostic GraphQL integration with Apollo, MongoDB and PostgreSQL integrations, code generation tooling in the x CLI, and live data for single documents and queries through X-Framework.

Two of those phrases carry the design. Database agnostic means the security and data layers are not tied to one store, and server agnostic means the GraphQL layer is not tied to one Node server implementation. That is what lets the same package set sit on MongoDB or SQL, which the README confirms by contrasting the packages with Blueprint: BlueLibs as a whole is not tied to GraphQL and MongoDB and supports SQL.

The intended user is a team that has decided its own architecture should follow SOLID principles and wants building blocks for it rather than a framework opinion imposed on it. The risk of that choice is obvious too. There is no house style enforced, so the discipline has to come from your team.

The monorepo holds packages, templates, scripts and assets

The repository layout is documented in the README and it explains how the project is built rather than how it is used.

# From Monorepo Root
chmod 755 /usr/local/bin/bluelibs-package-replace
sudo ln -s /usr/local/bin/bluelibs-package-replace `pwd`/scripts/bluelibs-package-replace

The monorepo is split into four directories. templates holds reusable things such as a new package template. scripts holds the things used for internal development, including the bluelibs-package-replace binary that the block above links into your PATH. packages holds all the packages themselves, and assets holds what is needed for the GitHub README page.

The root manifest is a private package named root at version 0.0.2 with a single devDependency, lerna at ^3.19.0. That is the whole build toolchain at the root: lerna does the linking and the publishing, and everything else lives inside the individual packages.

The lerna version is worth noticing, because lerna 3 predates the workspace protocol and the modern lerna release line. It works, and the README explains the workflow it implies, but it is a generation old in the package tooling world.

The CI configuration is a .circleci directory alongside a .travis.yml file, with the coverage badge pointing at CircleCI. Both configurations coexisting is a sign of a project that has been running for a long time without consolidating its pipeline.

lerna link is how one package sees a change in a sibling

The development loop for a monorepo with interdependent packages is the part the README spends most of its words on, and the answer is lerna link.

The explanation given is concrete. If a package depends on another, for example logger-bundle depends on core, you go into logger-bundle and run lerna link, then go to core and run npm run watch. logger-bundle then uses the updated version of core. The link operation points the dependency at the local working copy instead of the published package, and the watch script rebuilds core as you edit it.

That is the standard monorepo development answer, and the value of the README here is that it names the exact commands rather than leaving a new contributor to guess.

Each package uses jest and ts-jest for development testing, and the commands are short. For development runs there is npm run test:dev, and for the continuous integration run there is npm run test, which compiles the code and then runs the final tests. The split between a watch style development command and a compile then test command is the detail to copy.

The commit and branch conventions are documented too, with branch names shaped like feature/{package}/{issueNumber}-short-summary and fix/{package}/{issueNumber}-short-summary, and commit messages prefixed with the package name, for example fix(mongo-bundle): for a fix and deps({package}) for a dependency bump. Those conventions are the price of admission for contributing to a repository with this many packages.

bluelibs-package-replace points an outside app at your local build

lerna link solves the problem of a package depending on a sibling inside the monorepo. Testing a change against an application that lives outside the monorepo is a different problem, and the README gives it its own tool.

The bluelibs-package-replace binary has to be made executable and symlinked into a directory on your PATH, which the block in the previous section shows, with the target being the scripts directory of the monorepo. Once that is done, you go into your microservice and run bluelibs-package-replace x-ui, and it updates the package version in that application to the one you have in the monorepo. The README also insists that you keep watching changes in the package you replaced, with npm run watch, so the application sees new builds as you make them.

So there are two mechanisms with two scopes. lerna link is for packages inside the monorepo, and bluelibs-package-replace is for a consumer application outside it. Knowing which one you need before you start saves the confusion of a package that appears to update and does not.

The second step, sudo ln -s into /usr/local/bin, is the part that needs care. It writes outside the project, and on a machine without that directory the command fails outright.

The x CLI scaffolds a project that is already wired to GraphQL and MongoDB

The getting started path is short, and the first line of the README is an important qualification: the rapid prototyping solution, Blueprint for X-Framework, is tightly coupled to GraphQL and MongoDB, while BlueLibs as a whole is not and supports SQL.

npm i -g @bluelibs/x
x # pick project and complete it there
cd project
npm run blueprint:generate
npm run start:api
npm run start:admin # Start after API has started

The x CLI is installed globally, then invoked to pick a project template and complete it. Inside the generated project, npm run blueprint:generate produces the code, npm run start:api starts the API, and npm run start:admin starts the admin interface, which the comment says has to be started after the API. The prerequisites given are MongoDB and Node 14 or newer.

That ordering constraint is the kind of detail that only appears in a quick start. It also tells you the shape of the generated project: an API service and a separate admin frontend that depends on it.

The CLI also carries the code generation tooling, so npm run start:admin is not only a second server to remember but a consumer of the generated artifacts. The split between the CLI, the blueprint generator and the admin bundle is the practical topology of a BlueLibs project.

Documentation and code generation are the two things the project invests in

Two of the README's shorter paragraphs describe what surrounds the packages, and both are about developer experience rather than runtime behaviour.

The first is documentation. The project says it has designed a custom documentation experience with custom code snippets and challenges, hosted at its documentation page. Snippets that come from a real version of the package, and exercises that check the reader, are a differentiator from a documentation site that drifts out of sync with the code, and the code generation tooling exists partly to keep the two aligned.

The second is security reporting. If a vulnerability is found in one of the packages, the README asks for an email to Theodor Diaconu at [email protected] rather than a public issue, and states that vulnerabilities will be promptly addressed. A private channel for security reports is the convention every library project now follows.

Support itself runs through a Discord invite linked in the README badges, and the site is at bluelibs.com.

The gap worth naming is that the README documents the contribution mechanics in detail and the security channel in detail, and says comparatively little about the packages themselves. Each package has its own page under the documentation site, and those pages, not this repository README, are where the actual API reference lives.

MIT licensed, no tagged releases, and a lerna 3 root manifest

The BlueLibs ecosystem is open-sourced software licensed under the MIT License, with the terms in the LICENSE.md file at the root. MIT is the right choice for a set of packages meant to be mixed into someone else's application, and it means no copyleft obligation travels into a commercial product that uses them.

The last push to the repository was on 2026-10-09 and the project is not archived, so work continues. The repository publishes no GitHub releases, however, so there is no version stream to pin and no changelog to read at the ecosystem level. Each package carries its own version, and the README's example coordinates name a package, x-ui, without a version, which suggests the packages are consumed by name and range rather than by a lockstep release.

The dependency floors in the README tell you what era the tooling targets. Node 14 or newer is the stated requirement for the quick start, and lerna 3.19 is what the root manifest pins. Both work today, but they are not what a new project would choose, and the gap between the documented requirement and current practice is not documented anywhere in the README.

For an adopter, the practical risk is not the licence but the release surface. With no ecosystem level tags, deciding which version of which package to use means reading each package individually, and the monorepo's own conventions, commit formats and pull request process are the closest thing to a stability guarantee the project offers.

Editorial conclusion

BlueLibs fits a TypeScript team that wants a modular backend with dependency injection, a security layer and GraphQL, and that is willing to work in a lerna monorepo with its own package conventions rather than assembling NestJS, Passport and a GraphQL server separately. It does not fit a team that needs a maintained release stream, since the repository publishes no GitHub releases and the root manifest still pins lerna 3, or a team that wants to start with the rapid prototyping path and later swap MongoDB for SQL, because Blueprint is tied to GraphQL and MongoDB while only the packages are agnostic. Before you start, install the x CLI with npm i -g @bluelibs/x, and decide early whether you adopt the package set or the Blueprint workflow, because the two paths diverge on the database layer and on how much of the monorepo's own conventions you inherit.

Frequently asked questions

Official sources

1. bluelibs/bluelibs on GitHub
2. Issues
3. License: MIT
4. Project website
5. README