feat(dev_server): display compiler errors #120

quexpl · 2025-02-17T13:59:46Z

Inspired by Phoenix’s code reloading, this PR enhances Tableau’s error handling by displaying compiler errors directly in the browser.

Let me know if you'd like any modifications!

mhanberg · 2025-02-17T14:18:35Z

This is amazing! I'll take a closer look in the next couple days.

This might be a useful thing to extract to https://github.com/elixir-tools/web_dev_utils but that can come later.

mhanberg · 2025-03-02T17:31:12Z

Hi!

i was looking into your PR the other week, and had some thoughts.

first is, this doesn't actually show compiler errors for you project, only runtime errors once tableau attempts to build your site

secondly, with regard to the runtime error, it presents a confusing error, as its wrapped in tableau related code. I dont think this is necessarily at the fault of the code you've written, its more on tableau doesn't currently show more understandable errors when it fails, they're usually wrapped in tasks and are more hidden in the stack trace.

while I was investigating, I remembered that Plug already ships with Plug.Debugger to present views like this. I think all that is missing is to add that plug, and patch web_dev_utils to handle this use case a bit better

mhanberg · 2025-03-02T17:37:14Z

What I was testing were the following patches in tableau and web_dev_utils respectively

diff --git a/lib/tableau_dev_server/router.ex b/lib/tableau_dev_server/router.ex
index 699d042..9bccdac 100644
--- a/lib/tableau_dev_server/router.ex
+++ b/lib/tableau_dev_server/router.ex
@@ -1,6 +1,7 @@
 defmodule TableauDevServer.Router do
   @moduledoc false
   use Plug.Router, init_mode: :runtime
+  use Plug.Debugger
 
   require Logger
 
@@ -32,11 +33,19 @@ defmodule TableauDevServer.Router do
   end
 
   defp recompile(conn, _) do
-    if conn.request_path != "/ws" do
-      WebDevUtils.CodeReloader.reload()
+    if conn.request_path == "/ws" do
+      conn
+    else
+      case WebDevUtils.CodeReloader.reload() do
+        {:error, [error | _rest]} ->
+          with %{stacktrace: stacktrace, details: {:error, %exception{} = error}} <- error do
+            reraise exception, error |> Map.from_struct() |> Enum.to_list(), stacktrace
+          end
+
+        _ ->
+          conn
+      end
     end
-
-    conn
   end
 
   defp rerender(conn, _) do

diff --git a/lib/web_dev_utils/code_reloader.ex b/lib/web_dev_utils/code_reloader.ex
index 7a023ed..912f613 100644
--- a/lib/web_dev_utils/code_reloader.ex
+++ b/lib/web_dev_utils/code_reloader.ex
@@ -25,12 +25,12 @@ defmodule WebDevUtils.CodeReloader do
     {:ok, :nostate}
   end
 
-  def handle_call(:reload, from, state) do
-    froms = all_waiting([from])
-    mix_compile(Code.ensure_loaded(Mix.Task))
-    Enum.each(froms, &GenServer.reply(&1, :ok))
+  def handle_call(:reload, _from, state) do
+    froms = all_waiting([])
+    result = mix_compile(Code.ensure_loaded(Mix.Task))
+    Enum.each(froms, &GenServer.reply(&1, result))
 
-    {:noreply, state}
+    {:reply, result, state}
   end
 
   defp all_waiting(acc) do
@@ -43,6 +43,7 @@ defmodule WebDevUtils.CodeReloader do
 
   defp mix_compile({:error, _reason}) do
     Logger.error("Could not find Mix")
+    :error
   end
 
   defp mix_compile({:module, Mix.Task}) do

quexpl · 2025-03-03T14:01:45Z

Hi, thanks for getting back to this.
Very ncie use of Plug.Debugger, thanks for pointing that out! Without any changes to web_dev_utils it also seems to work properly and catch errors. Are changes to web_dev_utils required?

I only added use Plug.Debugger in router.ex and it worked, but as you wrote the error message is a bit misleading considering how Tableau works.

I tried to improve it a bit and added a change that wraps the exception and adds information about the page it occurred on. Maybe it's a bit better than showing the error itself, what do you think?

diff --git a/lib/mix/tasks/tableau.build.ex b/lib/mix/tasks/tableau.build.ex
index 4d03860..3c19cae 100644
--- a/lib/mix/tasks/tableau.build.ex
+++ b/lib/mix/tasks/tableau.build.ex
@@ -44,12 +44,17 @@ defmodule Mix.Tasks.Tableau.Build do
     pages =
       pages
       |> Task.async_stream(fn {mod, page} ->
-        content = Tableau.Document.render(graph, mod, token, page)
-        permalink = Nodable.permalink(mod)
-
-        Map.merge(page, %{body: content, permalink: permalink})
+        try do
+          content = Tableau.Document.render(graph, mod, token, page)
+          permalink = Nodable.permalink(mod)
+
+          Map.merge(page, %{body: content, permalink: permalink})
+        rescue
+          exception ->
+            reraise Tableau.BuildException, [page: page, exception: exception], __STACKTRACE__
+        end
       end)
-      |> Stream.map(fn {:ok, result} -> result end)
+      |> Stream.map(&map_pages/1)
       |> Enum.to_list()
 
     token = put_in(token.site[:pages], pages)
@@ -74,6 +79,12 @@ defmodule Mix.Tasks.Tableau.Build do
     token
   end
 
+  defp map_pages({:ok, result}), do: result
+
+  defp map_pages({:exit, {exception, stacktrace}}) do
+    reraise exception, stacktrace
+  end
+
   @file_extensions [".html"]
   defp build_file_path(out, permalink) do
     if Path.extname(permalink) in @file_extensions do


diff --git a/lib/tableau.ex b/lib/tableau.ex
index 6cc2449..1f0b77f 100644
--- a/lib/tableau.ex
+++ b/lib/tableau.ex
@@ -51,3 +51,29 @@ defmodule Tableau do
     MDEx.to_html!(content, Keyword.merge(config.markdown[:mdex], overrides))
   end
 end
+
+defmodule Tableau.BuildException do
+  @moduledoc false
+  @type t :: %__MODULE__{
+          page: map(),
+          exception: any()
+        }
+
+  defexception [:page, :exception]
+
+  @impl true
+  def exception(page: page, exception: exception) do
+    %__MODULE__{page: page, exception: exception}
+  end
+
+  @impl true
+  def message(%__MODULE__{page: page, exception: exception}) do
+    """
+    An exception was raised:
+      #{Exception.format_banner(:error, exception)}
+
+    occurred during the build process on the page:
+      #{inspect(page, pretty: true)}
+    """
+  end
+end


diff --git a/lib/tableau_dev_server/router.ex b/lib/tableau_dev_server/router.ex
index 699d042..d791994 100644
--- a/lib/tableau_dev_server/router.ex
+++ b/lib/tableau_dev_server/router.ex
@@ -1,6 +1,7 @@
 defmodule TableauDevServer.Router do
   @moduledoc false
   use Plug.Router, init_mode: :runtime
+  use Plug.Debugger
 
   require Logger

mhanberg · 2025-03-03T16:02:02Z

Are changes to web_dev_utils required?

Maybe not, but you've confirmed it works with a compiler error?

I think the diff you've commented looks good, feel free to push it up and i'll test it out myself, I want to see what it looks like in the terminal as well

quexpl · 2025-03-03T16:14:21Z

~~Yes it works fine with compiler and runtime errors.~~ Actually not! It renders errors, but there are not from compiler - so they are not so helpful.

quexpl · 2025-03-03T17:41:49Z

It's actually a bit more complicated . To have valuable compiler errors, we need yours changes to web_dev_utils.
Unfortunately, handling these errors in the router does not work correctly.
CodeReloader collects list of %Mix.Task.Compiler.Diagnostic with all warnings and errors returned by mix compile. For example:

{:error,
 [
   %Mix.Task.Compiler.Diagnostic{
     file: "/home/quex/workspace/elixir/blog/lib/MixFrontMatterFormatter.ex",
     source: "/home/quex/workspace/elixir/blog/lib/MixFrontMatterFormatter.ex",
     severity: :warning,
     message: "variable \"opts\" is unused (if the variable is not meant to be used, prefix it with an underscore)",
     position: {8, 24},
     compiler_name: "Elixir",
     span: {8, 28},
     details: nil,
     stacktrace: [
       {MixFrontmatterFormatter, :format, 2,
        [file: "lib/MixFrontMatterFormatter.ex", column: 24, line: 8]}
     ]
   },
   %Mix.Task.Compiler.Diagnostic{
     file: "/home/quex/workspace/elixir/blog/lib/layouts/app_layout.ex",
     source: "/home/quex/workspace/elixir/blog/lib/layouts/app_layout.ex",
     severity: :warning,
     message: "unused import Blog.CoreComponents",
     position: {5, 3},
     compiler_name: "Elixir",
     span: nil,
     details: nil,
     stacktrace: []
   },
   %Mix.Task.Compiler.Diagnostic{
     file: "/home/quex/workspace/elixir/blog/_layouts/post_layout.html.heex",
     source: "/home/quex/workspace/elixir/blog/_layouts/post_layout.html.heex",
     severity: :warning,
     message: "missing required attribute \"avatar\" for component Blog.CoreComponents.author/1",
     position: 3,
     compiler_name: "Elixir",
     span: nil,
     details: nil,
     stacktrace: [
       {:elixir_compiler, :__FILE__, 1,
        [file: ~c"_layouts/post_layout.html.heex", line: 3]}
     ]
   },
   %Mix.Task.Compiler.Diagnostic{
     file: "/home/quex/workspace/elixir/blog/lib/layouts/root_layout.ex",
     source: "/home/quex/workspace/elixir/blog/lib/layouts/root_layout.ex",
     severity: :warning,
     message: "unused import Blog.CoreComponents",
     position: {5, 3},
     compiler_name: "Elixir",
     span: nil,
     details: nil,
     stacktrace: []
   },
   %Mix.Task.Compiler.Diagnostic{
     file: "/home/quex/workspace/elixir/blog/lib/components/core_components.ex",
     source: "/home/quex/workspace/elixir/blog/lib/components/core_components.ex",
     severity: :error,
     message: "undefined function ffo/0 (expected Blog.CoreComponents to define such a function or for it to be imported, but none are available)",
     position: {7, 5},
     compiler_name: "Elixir",
     span: {7, 8},
     details: nil,
     stacktrace: [
       {Blog.CoreComponents, :"header (overridable 1)", 1,
        [file: "lib/components/core_components.ex", column: 5, line: 7]}
     ]
   },
   %Mix.Task.Compiler.Diagnostic{
     file: "/home/quex/workspace/elixir/blog/lib/components/core_components.ex",
     source: "/home/quex/workspace/elixir/blog/lib/components/core_components.ex",
     severity: :error,
     message: "** (CompileError) lib/components/core_components.ex: cannot compile module Blog.CoreComponents (errors have been logged)\n\n",
     position: 0,
     compiler_name: "Elixir",
     span: nil,
     details: {:error,
      %CompileError{
        file: "/home/quex/workspace/elixir/blog/lib/components/core_components.ex",
        line: 0,
        description: "cannot compile module Blog.CoreComponents (errors have been logged)"
      }},
     stacktrace: [
       {:elixir_module, :"-compile/7-fun-1-", 9,
        [file: ~c"src/elixir_module.erl", line: 215]},
       {:elixir_erl_compiler, :"-spawn/1-fun-0-", 3,
        [file: ~c"src/elixir_erl_compiler.erl", line: 19]}
     ]
   }
 ]}

I updated router.ex to only catch errors, combine messages, and raise a CompileError with the first error stack trace.

mhanberg · 2025-03-03T18:04:13Z

and raise a CompileError with the first error stack trace.

This is what the patch I commented with did.

I'll get the web dev utils patch released and we can update tableau and move get this merged

mhanberg · 2025-03-03T18:04:44Z

Now I'm thinking... tableau needs a logo to customize the error page with! Haha 😆

mhanberg · 2025-03-04T02:31:02Z

I released v0.3.0 of web dev utils, should unblock you

mhanberg · 2025-03-04T02:31:55Z

lib/mix/tasks/tableau.build.ex

+  defp map_pages({:ok, result}), do: result
+
+  defp map_pages({:exit, {exception, stacktrace}}) do
+    reraise exception, stacktrace
+  end
+


let's inline this function

Ok, I updated the code

mhanberg · 2025-03-04T02:33:24Z

lib/tableau_dev_server/router.ex

+        {:error, errors} ->
+          errors = Enum.filter(errors, &(&1.severity == :error))
+          message = Enum.reduce(errors, "", fn error, acc -> "#{acc}\n#{error.message}" end)
+          stacktrace = List.first(errors).stacktrace


this can fail if the list is is only non error severity, which would make List.first return nil

It should not fail as we are expecting error, first value in tuple is :error.
For the :ok it might return Mix.Task.Compiler.Diagnostic with warnings.

mhanberg · 2025-03-04T02:35:08Z

lib/tableau_dev_server/router.ex

+      case WebDevUtils.CodeReloader.reload() do
+        {:error, errors} ->
+          errors = Enum.filter(errors, &(&1.severity == :error))
+          message = Enum.reduce(errors, "", fn error, acc -> "#{acc}\n#{error.message}" end)


I think you just want Enum.map_join here

Enum.map_join(errors, "\n", & &1.message)

Ok, I updated the code

mhanberg · 2025-03-11T23:12:33Z

Tested locally, pretty sweet. I added some code to strip the ANSI escape sequences from the compiler errors.

Thanks a lot!

Capture errors with Plug.Debugger

547e1c7

quexpl force-pushed the rerender_compiler_errors branch from ae73368 to 547e1c7 Compare March 3, 2025 16:09

Handle compiler errors from code reloader

4ddcf14

mhanberg reviewed Mar 4, 2025

View reviewed changes

quexpl and others added 3 commits March 4, 2025 09:20

Implement changes from code review feedback

d088984

Bump web_dev_utils

b77b40b

strip ansi escape sequences from compiler error

aece5e3

mhanberg merged commit 0873535 into elixir-tools:main Mar 11, 2025
7 checks passed

github-actions bot mentioned this pull request Mar 11, 2025

chore(main): release 0.21.0 #121

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(dev_server): display compiler errors #120

feat(dev_server): display compiler errors #120

quexpl commented Feb 17, 2025

mhanberg commented Feb 17, 2025

mhanberg commented Mar 2, 2025

mhanberg commented Mar 2, 2025

quexpl commented Mar 3, 2025

mhanberg commented Mar 3, 2025

quexpl commented Mar 3, 2025 •

edited

Loading

quexpl commented Mar 3, 2025

mhanberg commented Mar 3, 2025

mhanberg commented Mar 3, 2025

mhanberg commented Mar 4, 2025

mhanberg Mar 4, 2025

quexpl Mar 4, 2025

mhanberg Mar 4, 2025

quexpl Mar 4, 2025

mhanberg Mar 4, 2025

quexpl Mar 4, 2025

mhanberg commented Mar 11, 2025

feat(dev_server): display compiler errors #120

feat(dev_server): display compiler errors #120

Conversation

quexpl commented Feb 17, 2025

mhanberg commented Feb 17, 2025

mhanberg commented Mar 2, 2025

mhanberg commented Mar 2, 2025

quexpl commented Mar 3, 2025

mhanberg commented Mar 3, 2025

quexpl commented Mar 3, 2025 • edited Loading

quexpl commented Mar 3, 2025

mhanberg commented Mar 3, 2025

mhanberg commented Mar 3, 2025

mhanberg commented Mar 4, 2025

mhanberg Mar 4, 2025

Choose a reason for hiding this comment

quexpl Mar 4, 2025

Choose a reason for hiding this comment

mhanberg Mar 4, 2025

Choose a reason for hiding this comment

quexpl Mar 4, 2025

Choose a reason for hiding this comment

mhanberg Mar 4, 2025

Choose a reason for hiding this comment

quexpl Mar 4, 2025

Choose a reason for hiding this comment

mhanberg commented Mar 11, 2025

quexpl commented Mar 3, 2025 •

edited

Loading