Installation

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

Prerequisites

• Elixir version 1.19 or higher
• OTP version 28.1 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.11.1"},

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).

Umbrella Projects

Hologram supports umbrella projects. The steps above apply to the child app that owns the Phoenix endpoint - it takes the Hologram dependency (step 1), the compiler entry (step 3), the router plug (step 4), the static asset configuration (step 5) and the gitignore entry (step 7).

Child apps that only define pages and components take the dependency alone, without the compiler entry. Their pages are discovered and bundled when the endpoint app compiles.

A few umbrella-specific details:

• Endpoint configuration lives in the umbrella root config directory, as it does for any umbrella app.
• Run mix holo from the umbrella root. Started from inside the endpoint app it watches only that app's sources, so changes in sibling apps will not trigger a live reload.
• Add listeners: [Phoenix.CodeReloader] to the project config in the umbrella root mix.exs. Mix reads listeners from the project it runs as, so the entry Phoenix generates in the endpoint app is not seen when mix holo runs from the root, and every reload logs a missing-listener warning.
• npm packages go in an assets directory at the umbrella root, and are resolved from there for every child app.
• Hologram supports one endpoint app per running BEAM instance. If several apps in the umbrella have a configured Phoenix endpoint, Hologram raises a descriptive error.

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