Journey of Upgrading an App to Phoenix 1.6

I'm really excited about the newly released Phoenix 1.6 because it provides the option to replace Webpack with esbuild, so that we no longer need Node for asset building.
Over the weekend, I managed to upgrade my little side project to Phoenix 1.6. In this talk I shared my journey.

Presented at Elixir Australia September 2021 Meetup: https://www.meetup.com/elixir-sydney/events/280659594

Recording video available at https://www.youtube.com/watch?v=NR_Jk3yUEqc

Transcript

1. Journey of Upgrading an App to Phoenix 1.6 by Qing Wu
2. Update dependencies def deps do [ {:phoenix, "~> 1.6.0-rc.0", override: true}, {:phoenix_html, "~> 3.0"}, {:phoenix_live_view, "~> 0.16.0"}, {:phoenix_live_dashboard, "~> 0.5"}, {:telemetry_metrics, "~> 0.6"}, {:telemetry_poller, "~> 0.5"}, ... ] end
3. esbuild for Javascript and CSS bundling
4. Phoenix asset pipeline review • All static assets are served from priv/static • Javascript: assets/js -> priv/static/js • CSS: assets/css -> priv/static/css • Images and other assets: assets/static -> priv/static
5. Remove webpack config and related node files $ cd assets $ rm webpack.config.js package.json package-lock.json .babelrc $ rm -rf node_modules
6. Add esbuild in deps def deps do [ ... {:esbuild, "~> 0.2", runtime: Mix.env() == :dev}, ] end
7. Configure esbuild # config/config.exs config :esbuild, version: "0.12.18", default: [ args: ~w(js/app.js --bundle --target=es2016 --outdir=../priv/static/assets), cd: Path.expand("../assets", __DIR__), env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)} ]
8. Update watcher in endpoint config # config/dev.exs config :your_web_app, YourWebApp.Endpoint, ..., watchers: [ esbuild: {Esbuild, :install_and_run, [:default, ~w(--sourcemap=inline --watch)]} ]
9. Move images and other assets • mv assets/static/* priv/static • Stop ignoring priv/static in VCS • Ignore priv/static/assets in VCS José's answer on Reddit
10. Add assets.deploy mix alias defp aliases do [ ..., "assets.deploy": ["esbuild default --minify", "phx.digest"] ] end
11. Remove local digest • mix phx.digest.clean --all
12. Update layouts # In `app.html.eex` or `root.html.eex`, update Routes.static_path(@conn, "/js/app.js") Routes.static_path(@conn, "/css/app.css") # to Routes.static_path(@conn, "/assets/app.js") Routes.static_path(@conn, "/assets/app.css")
13. Update Plug.Static configuration plug Plug.Static, at: "/", from: :my_app, gzip: false, only: ~w(assets fonts images favicon.ico robots.txt)
14. HEEx template engine • Make sure phoenix_live_view is in deps • Rename .html.eex and .html.leex templates to .html.heex • Update elixir expressions inside tags
15. Update Elixir expressions inside tags # child, not inside tag <h2>Hello <%= @name %></h2>
16. Update Elixir expressions inside tags <div id="<%= @id %>"> # to <div id={@id}>
17. Update Elixir expressions inside tags # EEx expression <a href="/prefix/<%= @item.text %>"> # this won't work <a href="/prefix/{@item.text}">
18. Update Elixir expressions inside tags # EEx expression <a href="/prefix/<%= @item.text %>"> # becomes <a href={"/prefix/#{@item.text}"}>
19. Deploy to Gigalixir • Remove phoenix_static_buildpack.config • add in elixir_buildpack.config hook_post_compile="eval mix assets.deploy && rm -f _build/esbuild"
20. New generators • phx.gen.auth • phx.gen.notifier
21. References • Phoenix 1.6.0-rc.0 Released • Phoenix 1.5.x to 1.6 upgrade instructions • Phoenix + esbuild + yarn + postcss + tailwindcss + cpx2 • Deploying on Gigalixir • Rubik's Cube Algorithms Trainer