Uniform - Less boilerplate, more code reuse in your portfolio of Elixir apps

Your Libraries & OS Mentoring Libraries
,
1

Announcing Uniform.

Uniform tries to minimize the work required to maintain a large portfolio of Elixir apps. It does this via centralization and automation.

How it works

Uniform works best when you have a portfolio of apps whose core is very similar. (For example, a suite of Phoenix LiveView apps that all use TailwindCSS.)

Here’s how it works:

  1. You build your entire portfolio of apps in a single, “vanilla” Elixir app. (No “umbrella” or “poncho” setup.) You can generate this “Base Project” with mix new, mix phx.new, etc.
  2. You use Uniform’s “blueprint” DSL to set up “base files” and mix dependencies that are required for every app.
  3. You “eject” each app into its own completely separate codebase using mix uniform.eject. The ejected codebase contains the exact project structure you need, with only the code relevant to that app.
  4. You deploy each app using these ejected codebases.
  5. (Recommended) You automate updating ejected codebases via CI, (with mix uniform.eject) so that they basically “update themselves”.

The sales pitch

When you embrace the Uniform approach, it can feel a bit like magic.

  • Security defect in all 10 of the apps you maintain? Fix it in your Base Project and :magic_wand: poof – it’s fixed everywhere.
  • Need to quickly prototype a new app? mix uniform.gen.app my_app and you’re off to the races. No need to set up your suite of common tools for the umpteenth time. (Re-running generators, adding configuration, etc.)
  • Have a private library in one app that you want to use in another? Modify a couple lines of Uniform configuration and it’s instantly available.
  • Want to update some Hex deps across a dozen apps? Update them in your Base Project and they’re updated everywhere.

Uniform tries to lower the amount of effort required for developers to get stuff done. It automates away the manual work needed to keep your codebases “uniform” – in total sync. (But only in the ways you prefer them to be.)

Request for feedback

We know this approach is unconventional to say the least. But we’ve been quietly iterating on it, and it’s working pretty well for us!

We’re very curious what the community at large thinks about this approach.

Links

Click here for the docs and guides.

The code snippets in the Setting up a Phoenix project guide show what it looks like to configure Uniform for a “real” project.

23 Likes
2

This looks really useful, and might be interesting to adapt to make it easier to eject into umbrella apps (one of the systems that I’m working on has client-specific modules).

If I might suggest, an example ejectable repo would be useful to better understand how Uniform works, though.

3 Likes
3

@halostatue Thanks for your input! Great point about an example repo. That’s next on the list. :slight_smile:

Also, great to know there’s potential demand to make it work with umbrella apps. For your scenario, how much granularity would you need? Is an “all or none” approach sufficient? (Either an app is shipped with all the files in an OTP app, or it’s not.) Or would you need to conditionally exclude certain files for certain apps?

4

Looks great!

5

I’m not entirely sure what we’d want. The class of apps that we would “eject” are fairly template-able (at least in the beginning), so our primary needs could probably be met if we bothered with a standard template from a repo…but having something that lets us sync certain dependencies across would also be useful.

6

Hmm, so are we talking white labeling? Or totally separate apps that just share a bunch of boilerplate and some identical features?

We didn’t build this for white labeling, but it would probably work really well for that.

7

Do they all share the same assets folder?

8

@cmo That’s up to you. You can configure/tailor it to mostly whatever your setup needs.

If you always want to include everything from assets, use cp_r. (Which is named after File.cp_r and running cp -r on the command line.)

base_files do
  cp_r "assets"
end

If you want to only eject certain files in assets depending on the app, maybe read this part of the Setting up a Phoenix project guide. Here’s a code snippet from there.

base_files do
  file "assets/#{app.name.underscore}/**/*.{js,ts}"
end

Which would eject all files in assets/my_app_name or its subdirectories that end in .js or .ts

All the tools at your disposal are explained in the docs for Blueprint. Most importantly, the base_files macro.

9

The latter, not white labelling, although that would be an interesting use case for other purposes.

We have a concept of a “client adapter module”, which starts from the same definition, but quickly gets customized to adapt to external client systems and data structures. There’s a lot of shared code within that, though.

10

@halostatue That sounds like it fits perfectly into Uniform’s model.

Are you currently using private Hex packages for that shared code? Copy-pasting it across codebases? Something else?

Feel free to hit me up on Elixir Slack (@paulstatezny) if you want to talk about specifics that you’re not comfortable sharing here. I’d be happy to walk you through a potential setup that fits your needs.

1 Like
11

The current code is…ad hoc and within the umbrella right now. What we’d be looking at retrofitting with Umbrella would be the management of those adapter submodules. I’m thinking we‘d have apps/adapter_template and then somehow do mix uniform.eject --umbrella to know it would be ejecting into the umbrella rather than to a new repo / package. There’s some other bits that would be good (and maybe Uniform could detect).

As I said, though, I’m not even quite sure what it is that we want, and we’ve got a few other overdue upgrade tasks that we’re working through now so we probably won’t be looking at this for a few weeks.

1 Like
12

@halostatue (and anyone else!) I added an example Uniform project on GitHub.

It’s quite barebones; the example apps are just facades. But it does include the basic structure of setting up Uniform for Phoenix apps. Over time we’ll need to add more to highlight the different features of Uniform.

You can see the codebases that are ejected from the base project here:

3 Likes