Installation

This guide will walk you through the installation process step by step.

Prerequisites

• Elixir version 1.15 or higher
• OTP version 24 or higher
• A working Phoenix application (Phoenix installation guide)
• Node.js version 20 or higher and npm, if not already installed, you can get them via asdf:

  $ asdf plugin add nodejs
  $ asdf install nodejs latest
  $ asdf global nodejs latest

  See asdf installation guide if you need to install asdf first.

1. Add Hologram Package

Add the Hologram package to your dependencies list in mix.exs:

{:hologram, "~> 0.8.3"},

2. Fetch Dependencies

Run the following command to fetch the Hologram package:

$ mix deps.get

3. Configure Compiler

Add the Hologram compiler to your project configuration in mix.exs:

def project do
  [
    # ...
    compilers: Mix.compilers() ++ [:hologram],
    # ...
  ]
end

4. Configure Router

Add the Hologram router plug before your Phoenix router plug in your endpoint:

defmodule MyAppWeb.Endpoint do
  # ...
  
  plug Hologram.Router
  plug MyAppWeb.Router
end

5. Configure Static Asset Serving

Add the Hologram directory to the list of served static directories in your endpoint:

plug Plug.Static,
  # ...
  only: ["hologram" | MyAppWeb.static_paths()]

6. Configure Formatter

Import Hologram formatter rules in .formatter.exs:

[
  # ...
  import_deps: [..., :hologram]
  # ...
]

If you use colocated .holo templates instead of the template/0 function in your page and component modules, also add holo to the file extension list in your inputs patterns so the formatter picks them up:

[
  # ...
  inputs: ["{app,config,lib,test}/**/*.{ex,exs,holo}", ...]
  # ...
]

7. Update GitIgnore

Add the following line to your .gitignore file to exclude Hologram generated JavaScript bundles:

# Hologram generated JavaScript bundles.
/priv/static/hologram/

8. Optional: Configure App Directory

Many developers prefer to organize their Hologram pages and components in an app directory outside of lib for better project structure. If you want to use this approach, modify your existing elixirc_paths/1 functions in mix.exs to include the app directory. These functions specify which directories Elixir should compile code from:

defp elixirc_paths(:test), do: ["app", "lib", "test/support"]
defp elixirc_paths(_env), do: ["app", "lib"]

This allows you to organize your code like app/pages/, app/components/, etc., which many developers find cleaner than keeping everything in lib/.

If you use the app directory, also add app to the directory list in your .formatter.exs inputs patterns so the formatter picks up files from it:

[
  # ...
  inputs: ["{app,config,lib,test}/**/*.{ex,exs,holo}", ...]
  # ...
]

Next Steps

After completing the installation, you can start building your isomorphic web application with Hologram. For more information on how to use Hologram's features, please refer to the website's Documentation section.

Notes

• Make sure all dependencies are properly installed and configured
• Verify that your Phoenix application is properly set up before installing Hologram