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.10.0"},

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}", ...]
  # ...
]

Running the App

Start your app with the mix holo task. It runs your Phoenix server with the Hologram compiler and client-side runtime enabled:

$ mix holo

In the dev and test environments, Hologram does not start with a plain mix phx.server - set the HOLOGRAM_START=1 environment variable to enable it (which is exactly what mix holo does). This keeps the Hologram compiler out of your workflow until you need it, so unrelated tasks and tests stay fast. Production builds always compile Hologram, so this applies only to dev and test.

Editor Support

The official Hologram extension adds syntax highlighting for .holo templates and ~HOLO sigils. Install it from the Visual Studio Marketplace (VS Code) or Open VSX Registry (Cursor, VSCodium, and other compatible editors).

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