All posts
OSGi · 10 min read · Jun 1, 2026

Lessons learned from managing hundreds of OSGi modules

Lessons learned from managing hundreds of OSGi modules

There is a moment in a large Liferay project when the module count crosses from helpful to overwhelming. Modularity is supposed to make a system easier to reason about, but past a certain size it introduces its own class of problems. After managing a codebase of several hundred bundles, a few lessons stand out, and most of them are about restraint rather than cleverness.

More modules is not better

Early enthusiasm for modularity tends to produce too many tiny bundles, each with one class and a pile of configuration. Every module adds build overhead, a manifest to maintain, and another node in the dependency graph. The right granularity is a module per cohesive capability, not per class. Splitting should follow a real boundary, not a reflex.

Build and deploy time become a tax

At scale, the slowest part of development is often the build itself. A few habits keep it manageable:

  • Build only the modules you changed, not the entire workspace, during day-to-day work.
  • Keep API modules stable so consumers rarely need rebuilding.
  • Use a baseline check to catch accidental breaking changes before they ripple outward.
  • Watch for modules that everything depends on; a change there forces a full rebuild.

The hardest bugs live between modules

Individual modules are usually easy to test and reason about. The bugs that consume days come from interactions: a service that is sometimes present and sometimes not, a configuration that resolves differently across environments, or a dependency cycle that only manifests under a particular start order. Investing in runtime observability (the Gogo shell, component state, clear logging) pays for itself many times over.

Conventions matter more than frameworks

With hundreds of modules and several developers, consistency is what keeps the system navigable. Shared conventions for package naming, module structure, and where configuration lives let any developer open an unfamiliar module and immediately understand it. The strongest large systems are not the ones with the cleverest architecture, but the ones where every module looks like every other module.

Restraint is the real skill

The recurring theme is restraint: fewer, better-bounded modules; stable APIs; consistent structure; and tooling that enforces the rules so humans do not have to remember them. Managing hundreds of modules well is less about mastering OSGi features and more about resisting the complexity that modularity makes easy to create.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar