Why does Phoenix 1.6 use html.heex as the suffix of the template file?

Because EEx is a universal template language, html.eex is used to indicate that this template is html content. Did I understand it correctly?

If so, I can’t understand why heex also uses this naming style. After all, heex means HTML EEx.

1 Like

EEx is completely ignorant of the surrounding text. It might as well be binary data I think. HEEx actually parses the HTML tags and will raise an error if the syntax is incorrect. One great advantage is, for example, a more concise interpolation syntax in the attributes which is much more friendly to the eye:
<.form for={@user} id={@form_id} {@add_attrs}></.form>


Alright, let’s say the new Phoenix release had used the html.eex file ending. How would tools like editors, GUI Git tools etc. know what they’re actually dealing with? In an html.eex file attribute interpolations with braces wouldn’t mean anything. But if we have the particular extension heex then the tooling can understand that it’s dealing with something that’s more than EEx.


I know that naming does not change the actual function of the template, it may affect the loading code of the template, editor plugins or readability. So there is no essential difference between a.html.eex and a.eex or a.html.heex and a.heex, I think everyone understands it.

I mainly think that naming the HEEx file html.heex is redundant. After all, heex can only represent html, right?

1 Like

It’s because of content negotiation *
With the .html.heex extension, phoenix will generate a render("foo.html", ...) clause in the view module. When rendering a page in the controller, passing :foo instead of "foo.html" or "foo.json" will make phoenix pick the correct clause based on the request headers.

The .html part of the name is used for content negotiation, and the .heex part is used to tell which compiler to use.

Content negotiation - HTTP | MDN (mozilla.org)
Phoenix.Controller — Phoenix v1.5.12 (hexdocs.pm) (rendering and layouts)
Phoenix.Controller — Phoenix v1.5.12 (hexdocs.pm) (render examples)

* That’s my conclusion, there may be other reasoning behind that


It is redundant, but only for tools that know what HEEx is. A text editor that doesn’t know anything about HEEx but does recognize the .html suffix can fall back to HTML syntax highlighting.

Also I think it’s pretty standard for templates to include the rendered file extension, even in cases where the engine is made for HTML. For example, slime templates tend to have a .html.slim suffix even though slim is HTML-specific.

No, that is not the case, the file extension is used to select the template engine that will compile the given template, .heex templates are handled by Phoenix.LiveView.HTMLEngine.

See Phoenix.Template - Custom Template Engines.

Also, the content type is used to select the format encoder.

See Phoenix.Template - Format encoders.

As @josemrb pointed to: The two extensions to the templates are for separate parts of the phoenix view layer.

The last part (usually heex, leex, eex, exs) selects the template encoder. It determines how the template content is turned into a function on the view module at compile time.

The middle part is for the content type, which is used at runtime for content negotiation, but also to select the format encoder. The format encoder turns the return value of the render function (maps for json, safe tuple for safe html, liveview rendered template struct) into actual iodata to send as response. This middle extension is also responsible so you can call the template by “index.html“.

Both of those parts are required for the view layer to work. The format encoders do not know anything about heex, given the the differences between heex and leex are purely handled at compile time and gone at runtime.

So while heex might be „html only“ the rest of the system is not at all aware of that.

1 Like