phoenixframework · rhcarvalho · Nov 27, 2025 · SteffenDE · Dec 8, 2025
diff --git a/guides/asset_management.md b/guides/asset_management.md
@@ -94,7 +94,7 @@ If you need to reference other directories, you need to update the arguments abo
 If you import a Node package that depends on additional fonts or images, you might find them to fail to load. This is because they are referenced in the JS or CSS but by default Esbuild will not touch or process referenced files. You can add arguments to esbuild in `config/config.exs` to ensure that the referenced resources are copied to the output folder. The following example would copy all referenced font files to the output folder and prefix the paths with `/assets/`:
 
 ```elixir
-args: ~w(js/app.js --bundle --target=es2017 --outdir=../priv/static/assets --external:/fonts/* --external:/images/* --public-path=/assets/ --loader:.woff=copy  --loader:.ttf=copy --loader:.eot=copy --loader:.woff2=copy),
+args: ~w(js/app.js --bundle --target=es2017 --outdir=../priv/static/assets --external:/fonts/* --external:/images/* --public-path=/assets/ --loader:.woff=copy --loader:.ttf=copy --loader:.eot=copy --loader:.woff2=copy),
 ```
 For more information, see [the esbuild documentation](https://esbuild.github.io/content-types/#copy).
 

diff --git a/guides/howto/custom_error_pages.md b/guides/howto/custom_error_pages.md
@@ -90,7 +90,7 @@ Phoenix generates an `ErrorHTML` for us, but it doesn't give us a `lib/hello_web
     <meta name="viewport" content="width=device-width, initial-scale=1"/>
     <title>Welcome to Phoenix!</title>
     <link rel="stylesheet" href="/assets/css/app.css"/>
-    <script defer type="text/javascript" src="/assets/js/app.js"></script>
+    <script type="module" src="/assets/js/app.js"></script>
   </head>
   <body>
     <header>

diff --git a/guides/real_time/channels.md b/guides/real_time/channels.md
@@ -432,7 +432,7 @@ Next, we need to pass this token to JavaScript. We can do so inside a script tag
 
 ```heex
 <script>window.userToken = "<%= assigns[:user_token] %>";</script>
-<script src={~p"/assets/js/app.js"}></script>
+<script type="module" src={~p"/assets/js/app.js"}></script>
 ```
 
 ### Step 4 - Pass the Token to the Socket Constructor and Verify

diff --git a/installer/templates/phx_single/config/config.exs b/installer/templates/phx_single/config/config.exs
@@ -37,8 +37,16 @@ config :<%= @app_name %>, <%= @app_module %>.Mailer, adapter: Swoosh.Adapters.Lo
 config :esbuild,
   version: "0.25.4",
   <%= @app_name %>: [
-    args:
-      ~w(js/app.js --bundle --target=es2022 --outdir=../priv/static/assets/js --external:/fonts/* --external:/images/* --alias:@=.),
+    args: ~w(
+      js/app.js
+      --bundle
+      --format=esm
+      --target=es2022
+      --outdir=../priv/static/assets/js
+      --external:/fonts/*
+      --external:/images/*
+      --alias:@=.
+    ),
     cd: Path.expand("..<%= if @in_umbrella, do: "/apps/#{@app_name}" %>/assets", __DIR__),
     env: %{"NODE_PATH" => [Path.expand("../deps", __DIR__), Mix.Project.build_path()]}
   ]<% end %><%= if @css do %>

diff --git a/installer/templates/phx_umbrella/apps/app_name_web/config/config.exs b/installer/templates/phx_umbrella/apps/app_name_web/config/config.exs
@@ -21,8 +21,16 @@ config :<%= @web_app_name %>, <%= @endpoint_module %>,
 config :esbuild,
   version: "0.25.4",
   <%= @web_app_name %>: [
-    args:
-      ~w(js/app.js --bundle --target=es2022 --outdir=../priv/static/assets/js --external:/fonts/* --external:/images/* --alias:@=.),
+    args: ~w(
+      js/app.js
+      --bundle
+      --format=esm
+      --target=es2022
+      --outdir=../priv/static/assets/js
+      --external:/fonts/*
+      --external:/images/*
+      --alias:@=.
+    ),
     cd: Path.expand("../apps/<%= @web_app_name %>/assets", __DIR__),
     env: %{"NODE_PATH" => [Path.expand("../deps", __DIR__), Mix.Project.build_path()]}
   ]<% end %><%= if @css do %>

diff --git a/installer/templates/phx_web/components/layouts/root.html.heex b/installer/templates/phx_web/components/layouts/root.html.heex
@@ -9,7 +9,7 @@
     </.live_title>
     <link phx-track-static rel="stylesheet" href={~p"/assets/css/app.css"} /><%= if not @css do %>
     <link phx-track-static rel="stylesheet" href={~p"/assets/default.css"} /><% end %>
-    <script defer phx-track-static type="text/javascript" src={~p"/assets/js/app.js"}>
+    <script phx-track-static type="module" src={~p"/assets/js/app.js"}>
     </script><%= if @css do %>
     <script>
       (() => {

diff --git a/installer/test/phx_new_test.exs b/installer/test/phx_new_test.exs
@@ -165,8 +165,9 @@ defmodule Mix.Tasks.Phx.NewTest do
       assert File.exists?("phx_blog/assets/vendor")
 
       assert_file("phx_blog/config/config.exs", fn file ->
-        assert file =~ "cd: Path.expand(\"../assets\", __DIR__)"
         assert file =~ "config :esbuild"
+        assert file =~ "--format=esm"
+        assert file =~ "cd: Path.expand(\"../assets\", __DIR__)"
       end)
 
       # Ecto

diff --git a/installer/test/phx_new_umbrella_test.exs b/installer/test/phx_new_umbrella_test.exs
@@ -60,7 +60,8 @@ defmodule Mix.Tasks.Phx.New.UmbrellaTest do
       end)
 
       assert_file(root_path(@app, "config/config.exs"), fn file ->
-        assert file =~ ~r/config :esbuild/
+        assert file =~ "config :esbuild"
+        assert file =~ "--format=esm"
         assert file =~ "cd: Path.expand(\"../apps/phx_umb_web/assets\", __DIR__)"
         assert file =~ ~S[import_config "#{config_env()}.exs"]
         assert file =~ "config :phoenix, :json_library, Jason"