I consider this a work in progress. This is a guide that I'll use myself as I migrate all my projects to 1.7 so it will refine over time and please submit comments / suggestions for improvements.
The Problem
I have several older projects that are in the Phoenix 1.6 style and structure, and lots of newer ones in 1.7. In order to share code and solutions between them I need to move them all to 1.7 and do it by making the 1.6 look exactly like a project started on 1.7.
Therefore, I'm moving things and removing things resulting in changes that may not be strictly necessary if you are just trying to get 1.7 to run.
Some other good tutorials exist that can be helpful to just make a project work, for example by adding Views back into the project via an optional dependency.
Steps
0. Create a branch in git
Disclaimer
In order to make the app look like a true 1.7 app, we need to move, edit and delete a lot of files.
Start with creating a branch in git in case you ever need to revert or reference the 1.6 code:
git checkout -b phoenix_1_6
git checkout -b upgrading_to_1_7
I also suggest that you keep a separate clone of the old version, or at least grab the list of generated routes for use later when you convert to path sigils:
mix phx.routes > routes.txt
(I'm saying store it because once you start making these changes your project may not compile again until all the issues are fixed. In my latest conversion, there were over 800 issues to be fixed to get the project to compile again.)
1. Update dependencies
List of deps that I changed:
defp deps do
[
{:phoenix, "~> 1.7.10"},
{:phoenix_html, "~> 3.3"},
{:phoenix_live_reload, "~> 1.2", only: [:dev]},
{:phoenix_live_view, "~> 0.19"},
{:phoenix_live_dashboard, "~> 0.8.0"},
{:esbuild, "~> 0.7", runtime: Mix.env() == :dev},
...
Run:
mix deps.clean --all
rm mix.lock
mix deps.get
mix deps.compile
2. Fix issues related to Views
Phoenix 1.7 removed the view files so things need to be updated. You'll see errors like:
error: module Phoenix.View is not loaded and could not be found. This may be happening because the module you are trying to load directly or indirectly depends on the current module
...
Instead, Phoenix 1.7 uses html_template
embedding modules. (See Step 5)
Take note of any functionality that you may have added to your *_view.ex
modules. This will likely move into your *_html.ex
files that we'll create in Step 5.
I suggest keeping those View
modules for now, but remove the use <App>Web, :view
so that it won't throw compilation errors.
But if you only have boilerplate code in /views
then you can safely remove those files and that directory:
# NOTE: Only if you don't need to keep any of those files
# Otherwise run this after Step 5.
rm -fr lib/appName_web/views
3. Create components dir
This is where layouts and standard components will live now.
mkdir lib/<app>_web/components
Move you layouts from the former templates
dir:
mv lib/<app>_web/templates/layouts lib/<app>_web/components/.
Note: If you have a live.html.heex
layout, you should be able to remove it. One of the major benefits of 1.7 is that the layouts are shared across live and dead views.
4. Move template dirs
Instead of being in a separate templates
directory, the remaining templates folders with the *.html.heex
files move into the controllers
dir as subfolders:
mv lib/appName_web/templates/* lib/appName_web/controllers/.
Note: I then manually renamed them to include the standard _html
suffix.
cd lib/appName_web/controllers
mv page page_html
mv post post_html
After that you should be able to get rid of the templates dir:
rm -fr lib/appName_web/templates
5. Add the html embedding modules
Let's say you still have a PageController. You'll want to add a companion file next to the page_controller.ex
conventionally called page_html.ex
which looks like this by default:
defmodule AppNameWeb.PageHTML do
use AppNameWeb, :html
embed_templates "page_html/*"
end
You will probably get an error that :html
is an unknown function in your app's web module. You'll need to find your base module at lib/appName_web/appName_web.ex
and change a few functions.
Add: html
, html_helpers
, verified_routes
, and static_paths
:
def html do
quote do
use Phoenix.Component
# Import convenience functions from controllers
import Phoenix.Controller,
only: [get_csrf_token: 0, view_module: 1, view_template: 1]
# Include general helpers for rendering HTML
unquote(html_helpers())
end
end
defp html_helpers do
quote do
# HTML escaping functionality
import Phoenix.HTML
# Core UI components and translation
import AppNameWeb.CoreComponents
import AppNameWeb.Gettext
# Shortcut for generating JS commands
alias Phoenix.LiveView.JS
# Routes generation with the ~p sigil
unquote(verified_routes())
end
end
def verified_routes do
quote do
use Phoenix.VerifiedRoutes,
endpoint: AppNameWeb.Endpoint,
router: AppNameWeb.Router,
statics: AppNameWeb.static_paths()
end
end
def static_paths, do: ~w(assets fonts images favicon.ico robots.txt)
Remove component
, view
and view_helpers
Update references to view_helpers
to html_helpers
Also - update the controller
,live_view
and live_component
function:
def controller do
quote do
use Phoenix.Controller,
formats: [:html, :json],
layouts: [html: AppNameWeb.Layouts]
import Plug.Conn
import AppNameWeb.Gettext
unquote(verified_routes())
end
end
def live_view do
quote do
use Phoenix.LiveView,
layout: {AppNameWeb.Layouts, :app}
unquote(html_helpers())
end
end
def live_component do
quote do
use Phoenix.LiveComponent
unquote(html_helpers())
end
end
6. Add standard files
Add some components
Grab the core_components.ex
and layouts.ex
from any 1.7 projects or clone this example project and put it into lib/appName_web/components
Add Gettext
If you don't have GetText in the base of your app then grab that too from lib/appName_web/gettext.ex
Make sure you updated "appName"
Make sure this doesn't find anything:
grep -ri lib appname
7. Small change to the csrf_token
Your root.html.heex
layout probably has a function call like:
csrf_token_value()
This needs to change to:
get_csrf_token()
8. Update router
The :browser
pipeline needs to reference the layouts with the new module name. Change:
#from
plug :put_root_layout, {AppNameWeb.LayoutView, :root}
#to
plug :put_root_layout, html: {AppNameWeb.Layouts, :root}
9. Update Routes to use ~p
sigil
Now you can use the much more convenient ~p
sigil.
Look in all of your html for references to Routes.
and change them similar to the following examples:
# from:
href={Routes.static_path(@conn, "/assets/app.css")}
# to:
href={~p"/assets/app.css"}
# from
<img src={Routes.static_path(@conn, "/images/logo.png")}
# to
<img src={~p"/images/logo.png")}
# from
Routes.post_path(@conn, :index)
# to
~p"/posts"
# from
Routes.post_path(@conn, :update, @post)
# to
~p"/admin/prompts/#{@prompt}"
10. Update heex to use components
Instead of embedding elixir code into templates with <%= ... %>
, convert these snippets to components where appropriate.
Some example replacements:
# from:
<%= live_title_tag assigns[:page_title] || "App" %>
# to:
<.live_title suffix="">
<%= assigns[:page_title] || "App" %>
</.live_title>
# from:
<%= render 'form.html', ... %>
# to:
<.post_form changeset={@changeset} action={~p"/posts/update/#{@post}"} />
# from:
<%= link "Edit", to: Routes.page_path(@conn, :edit, @page) %>
# to:
<.link navigate={~p"/pages/#{@page}"}>Edit</.link>
# from:
<%= link "Delete", to: Routes.page_path(@conn, :delete, page), method: :delete, data: [confirm: "Are you sure you want to delete #{page.title}?"] %>
# to:
<.link href={~p"/mascots/#{mascot}"} method="delete" data-confirm="Are you sure?">
Delete
</.link>
# from:
<%= label f, :name %>
<%= text_input f, :name %>
<%= error_tag f, :name %>
# to:
<.input field={f[:name]} type="text" label="Name" />
# from:
<%= inputs_for f, :children, fn c -> %>
<%= label c, :baby_name %>
<%= text_input c, :baby_name %>
<%= error_tag c, :baby_name %>
# to:
# from:
<%= if @changeset.action do %>
<div class="alert alert-danger">
<p>Oops, something went wrong! Please check the errors below.</p>
</div>
<% end %>
# to:
<.error :if={@changeset.action}>
Oops, something went wrong! Please check the errors below.
</.error>
# from:
<div class="buttons">
<%= submit "Save" %>
</div>
# to:
<:actions>
<.button>Save</.button>
</:actions>
TIP: Keep a 1.7 generated app nearby with a some forms etc created with mix phx.gen.html ...
for comparisons during this phase.
10B - Check that you didn't miss anything
Here are a few scripts to run against your lib dir to find missed replacements:
grep -r lib "<%= link"
11. Update various heex items
The form
component now needs :let
instead of let
.
You could try bulk updating like this:
# MacOS
find lib -type f -name "*.heex" -exec sed -i '' 's/form let/form :let/g' {} +
# Linux
find lib -type f -name "*.heex" -exec sed -i 's/form let/form :let/g' {} +
If this was helpful - give it a Like and Follow!
Happy Coding.
Top comments (0)