Fireside - Installable & Upgradable Code Templates

Your Libraries & OS Mentoring Libraries
, , ,
1

Hello all!

Announcing Fireside, a tool to install and upgrade code templates that are themselves Elixir apps.

Fireside allows you to bring over microservices directly into your Elixir monolith. As an example, I built and open-sourced an e-commerce core for an online store (used in a real platform), and Fireside lets you install everything it needs to run in just one command: mix fireside.install shopifex@github:ibarakaiev/shopifex. This will:

  1. Install all its dependencies (as well as their Igniter installers, if available).
  2. Import all files listed in fireside.exs of the component.
  3. Run an optional setup/1 hook that uses Igniter for custom things like modifying config.exs, running mix tasks, etc.
  4. Calculate the hash of the AST of each imported file and record it in config/fireside.exs.

Then, if the component changes in the remote, you can bring over changes with mix fireside.update shopifex. Fireside components can even expose an upgrade/3 function that can run Igniter modifications. It’s kind of like a database migration, but for your app (or, rather, for an isolated part of it).

However, if you modify the imported code, Fireside will detect it by looking at the hash of its new AST and will reject updates. This is so that you can change the imported code and not risk having your changes overwritten. For this use case, it’s recommended to “unlock” the component before editing with mix fireside.unlock {component}, more on which below.

Some use cases, like project starter templates or code from tutorials, don’t require “locking”, and can be installed with the --unlocked flag. In this case, Fireside will import the code once and forget about it. This would be useful for something like phx.new if it were created with Fireside, in which case it would be possible to add a Phoenix template to an existing Elixir app. Updating or removing (mix fireside.uninstall) would not be possible in this case.

The key difference between regular code templates and Fireside components is that Fireside is AST-aware (thanks to Igniter!) and Fireside components are themselves standalone Elixir apps that you can test and build in any way you want—“exporting” only the critical parts. I wrote a bit more about the motivations and potential use cases in a blog post: Embedded Microservices and Fireside.

If you want to take it for a spin, feel free to take a look at the README and Creating a Fireside Component. If you do like it, let me know here or by leaving a star in the repo :slight_smile:

9 Likes