What’s wrong with Umbrella Apps?

I’ll let more experienced folks chime in regarding the technical reasons.

My personal experience from working in a few large umbrella projects (note that this is not due to the tech itself, just what happened with the folks using it) have mostly shown issues with premature and incorrect separation of concerns. This is a human problem, not a tech one. Symptoms of these are having sub-apps called core, core_db, utils… that are required everywhere in a project. Basically, instead of thinking in contexts within a non-umbrella app, folks try (incorrectly) to abstract those into apps. Sometimes, they mean well too.

If you can’t run tests in your sub-app without requiring other apps, you should likely have a flat structure and use contexts instead. If you have issues with dependencies (your own), you should reconsider the structure as well. Folks can use behaviours and define boundaries within the contexts if they are inclined (and get Mox for free out of the box if done properly). If you share the same database and have multiple sub-apps calling into it (and having issues with it), maybe your abstraction is incorrect. It is self imposed complexity most of the time. Some folks just want to do it too, because, they can.

These have been the bad experiences with it. Again, this is not related to the umbrella structure itself, but they did happen with folks that used it because they could.

This reminds me of the hippo story from “Along came Polly”. If you are a hippo, be a hippo. If you are a flat app, it’s ok! https://www.youtube.com/watch?v=uhOzaH0GbEg

I think by and large the problem is similar to “don’t use GenServers for code organization”. Likewise, often times people use umbrellas to organize their code, when umbrellas are best used when you have deployment heterogeneity (I think).

They are bad for organization because:

• they create an extra layer of indirection in your file paths (apps/ directory)
• it’s easy to wind up with intra-app dependencies that you lose track of.
• grokking the mix.exs paths is tricky
• some libraries don’t support umbrellas

A better solution is to just be unafraid to make top level namespaces in the main app (like how Phoenix creates MyApp and MyAppWeb). For example, I often have a Type module that contains project-specific Typing, and a Tools module, and a Db module.

That’s a very good point about wrong separation of concerns. I personally worked on an Umbrella app and it was fine and manageable.

I’ve read that an issue with umbrellas is a dependency conflict if app1 needs one version of a package, and app2 needs another version. For my case it was never an issue though.

maybe this is no longer an issue, but I found it much slower to compile

I’ve found an umbrella structure really useful when you have multiple independent UIs to a single source-of-truth, especially when each UI wants its own asset compilation settings.

Some of the pain-points are mostly historical (for instance, the generator doesn’t even create config directories in sub-apps anymore, because the load order doesn’t work like that anyways) but there are definitely libraries that still rely on global config despite recommendations against it.

Enforcing this is actually one of the benefits of an umbrella project. Any subset of the apps in the umbrella could be deployed together in a release. If they can appear in the same release, then they need to depend on the same version of an external app.

Totally agree on this. That’s what I’m using umbrella for.

I’m still trying to figure out how to achieve that without umbrella but so far umbrella provides all I need out of the box for that with its generators :

Multiple endpoints listening on different port with their own router, assets, gettext translations etc. If I try to put those Phoenix apps in a single app I would have to do a lot more tweaks to achieve the “same goal”.

On the other hand some generators don’t support umbrella yet but I guess that could change in the future. For example mix phx.gen.release but it’s not a big deal.

My two reasons for not using umbrellas:

1. Using mix xref ... to try and reduce compile-time dependencies between modules was near-impossible. Not sure if things improved since Elixir 1.11 on that but back then it was a huge turn-off for me.
2. A number of libraries that generate code inside your project don’t support umbrellas.

None of these are huge or actual show-stoppers but then again, working in a professional setting where you are paid to be productive introduces the problem of not having too much time to fiddle with such problems when they arise. So I eventually gave up, it didn’t seem to be worth the hassle to use umbrellas unless you really needed them – and several posters have provided legitimate needs for umbrellas already with which I fully agree.

The compile-time dependency thing is much improved in either 1.11 or 1.12 - it’s no longer possible to have “accidental” dependencies on other apps in the umbrella (where AppA references AppB.Something but does not declare AppB in deps) without a compiler warning. As a corollary, circular dependencies between subapps will always either trigger that warning (if the dep is not declared) or fail outright (if both subapps declare a dependency on each other).

I’d upvote this more than once if I could. mix xref doesn’t play nice at all with umbrella applications. It’s a PITA to make it work and find links between applications, and answering questions like “how much of this codebase is affected if I refactor this one function?” are very difficult to answer when your tools don’t understand umbrellas well enough.

This is a big point for me, not to mention that OTP applications are a runtime and deployment concern, not a code separation tool, so it doesn’t even make sense to use an umbrella for code organization in the first place. Tools like GitHub - sasa1977/boundary: Manage and restrain cross-module dependencies in Elixir projects · GitHub offer a better way to tackle the “I don’t want code from this module to be called by this other module” problem in a saner way that doesn’t break most of the tools out there.

Also the fact that you have to append “in an umbrella app” whenever you ask someone for advice on fixing your weird bug should be a sign that something is off from the start.

I’d like for people to ask the question the other way around: why introduce umbrellas in the first place? rather than thinking that an umbrella is a good idea because reasons and then trying to find pain points later on.