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.

Pre-requirements

Before upgrading Phoenix itself to v1.7, we recommend first updating some Phoenix dependencies in mix.exs: phoenix_view (add it if missing), phoenix_live_view (if you were explictly using LiveView before), and phoenix_live_dashboard.

def deps do
  [
    {:phoenix_view, "~> 2.0"},
    {:phoenix_live_view, "~> 0.18.18"},
    {:phoenix_live_dashboard, "~> 0.7.2"},
    ...
  ]
end

If you are currently using Phoenix LiveView v0.17 or earlier, please read and follow the LiveView CHANGELOG before continuing.

Update to Phoenix v1.7

With dependencies updated, updating to Phoenix v1.7 should be as simple as bumping its requirement:

def deps do
  [
    {:phoenix, "~> 1.7.0"},
    ...
  ]
end

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

These are longer necessary on Elixir v1.11+:

  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, :ecto_sql, :phoenix],
  subdirectories: ["priv/*/migrations"],
  plugins: [Phoenix.LiveView.HTMLFormatter],
  inputs: ["*.{heex,ex,exs}", "{config,lib,test}/**/*.{heex,ex,exs}", "priv/*/seeds.exs"]
]

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) 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.

(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!

(optional) Migrate from Phoenix.View to Phoenix.Component

Phoenix v1.6 used Phoenix.View to render templates, Phoenix v1.7 defaults to Phoenix.Component. Phoenix.View is not deprecated and it is still supported. Old applications can depend on it as they prefer. However, if you want to migrate to Phoenix.Component, we have written helpful steps in the Phoenix.View documentation.

@Intelliractive you probably are using the deprecated version of let instead of :let. The former was removed with LiveView 0.19.0.

So instead of <.form let={f} for={@changeset}> ... you have to use <.form :let={f} for={@changeset}>

@gerritwalther thank you, I had the exact same problem and that was the fix.

After migrating to phoenix 17 with verified routes, these seems to work as expected but the compiler does not throw warnings when using invalid routes (I'm using elixir 14).

After migrating to phoenix 17 with verified routes, these seems to work as expected but the compiler does not throw warnings when using invalid routes (I'm using elixir 14).

In case someone encounters this situation, be aware that having a /* path in your router will cause all routes to be considered valid. For example:

 scope "/" do
      get "/*path", ExampleController, :index
    end