phoenix-1.6.x-1.7-upgrade.md

Upgrading from Phoenix v1.6.x to v1.7.0

Most of the new features and requirements for v1.7 are optional and many folks will simpy be able to bump their mix.exs version and compile without issue, though a few warnings will be reported.

Upgrade to Elixir v1.14.0

While not a hard requirement, Elixir v1.14.0 provides new compiler features to support proper warnings for the new Phoenix.VerifiedRoutes feature as well as Phoenix LiveView 0.18's new declarative assigns.

Update your deps:

Update your Phoenix, Phoenix LiveView, and Phoenix Live Dashboard deps in mix.exs.

def deps do
  [
    {:phoenix, "~> 1.7.0-rc.0", override: true},
    {:phoenix_live_view, "~> 0.18.3"},
    {:phoenix_live_dashboard, "~> 0.7.2"},
    ...
  ]
end

Remove the :phoenix and :gettext compilers from your mix.exss project/0 :compilers configuration

These are longer necessary on Elixir v1.14+

  def project do
    [
-     compilers: [:phoenix, :gettext] ++ Mix.compilers(),
    ]
  end

Update your .formatter.exs

To support the latest Phoenix.LiveView HTML formatter and declarative assigns macros, update your .formatter.exs as follows with the Phoenix.LiveView.HTMLFormatter plugin:

[
  import_deps: [:ecto, :phoenix],
  subdirectories: ["priv/*/migrations"],
  plugins: [Phoenix.LiveView.HTMLFormatter],
  inputs: ["*.{heex,ex,exs}", "{config,lib,test}/**/*.{heex,ex,exs}", "priv/*/seeds.exs"]
]

Update your LiveView imports

Phoenix.LiveView.Helpers has been soft deprecated and all relevant functionality has been migrated. You must import Phoenix.Component where you previously imported Phoenix.LiveView.Helpers when upgrading (such as in your lib/app_web.ex). You may also need to import Phoenix.Component where you also imported Phoenix.LiveView and some of its functions have been moved to Phoenix.Component.

live_title_tag has also been renamed to live_title as a function component. Update your root.html.heex layout to use the new component:

-   <%= live_title_tag assigns[:page_title] || "Onesixfifteen", suffix: " · Phoenix Framework" %>
+   <.live_title suffix=" · Phoenix Framework">
+     <%= assigns[:page_title] || "MyApp" %>
+   </.live_title>

Optional Updates

The remaining updates are optional and only necessary if you intend to make use of the new verified routes, or phx.gen.html|live|auth generators in an existing application. The generators follow new conventions and make use of the new function component approach to building templates. While these changes are a big step forward for new applications, it probably makes sense to maintain your current application conventions and skip these steps for established, large 1.6 applications.

(optional) Update your app to support Phoenix.VerifiedRoutes

You can read more about verified routes here

Add the following lines to your lib/app_web.ex:

+ def static_paths, do: ~w(assets fonts images favicon.ico robots.txt)
  
  def controller do
    quote do
      use Phoenix.Controller, namespace: DemoWeb

      import Plug.Conn
      import DemoWeb.Gettext

+     unquote(verified_routes())
    end
  end    

  defp view_helpers do
    quote do
      ...
+     unquote(verified_routes())
    end
  end
  
+ def verified_routes do
+   quote do
+     use Phoenix.VerifiedRoutes,
+       endpoint: DemoWeb.Endpoint,
+       router: DemoWeb.Router,
+       statics: DemoWeb.static_paths()
+   end
+ end

Next, update your lib/app_web/endpoint.ex's Plug.Static to reference the static_paths function:

  plug Plug.Static,
    at: "/",
    from: :app,
    gzip: false,
-   only: ~w(assets fonts images favicon.ico robots.txt)
+   only: AppWeb.static_paths()

Lastly, update your test/support/conn_case.ex to use verified routes:

  using do
    quote do
      # The default endpoint for testing
      @endpoint DemoWeb.Endpoint

+     use AppWeb, :verified_routes

      # Import conveniences for testing with connections
      import Plug.Conn
      import Phoenix.ConnTest
      import AppWeb.ConnCase
    end
  end

You're now set up to use ~p throughout your web and test stack. Enjoy!

When talking about removing :phoenix and :gettext from the mix.exs compilers list, the diff shows removing the whole line including Mix.compilers(). I don't think you mean to suggest removing the whole line. I'm on Elixir 1.14.1 and if I remove the whole line I get an error that I can't compile cowlib.

@chrismccord I think https://hexdocs.pm/phoenix_view/Phoenix.View.html#module-migrating-to-phoenix-component this is missing from the upgrade guide. Phoenix 1.7 simplifies the structure quite a bit. Thanks a lot.

If you upgrade without removing views, you need to add Phoenix.View to mix.exs dependencies:

{:phoenix_view, "~> 2.0"}

I think it might be worth noting if you don't want to migrate from phoenix_view just yet you have to manually add it as a dependency, otherwise you just get an error about the missing module

The instructions have an inconsistency in the naming of the application. DemoWeb vs AppWeb

Thanks so much for this. One thing that might also be worth mentioning is that if people are using live_reload they'll likely need to update the patterns for the new folder structure and to also match .heex files.