I recently generated the boilerplate for a new mix app using the Phoenix 1.3.1 phx.new generator and realized that the structure of the web directory and namespace have changed after 1.3-rc, which was structured differently than the 1.3.x release variants, namely 1.3.0, 1.3.1, and 1.3.2. Because I already had a production Phoenix app based on the 1.3-rc structure (upgraded from 1.2) running under the same umbrella, I wanted to update that app to match the structure of the formally released 1.3.x variants.

Fundamentally these changes are very simple:

• The MyApp.Web module becomes MyAppWeb.
• The top-level MyApp namespace no longer contains the OTP application configuration for the app. This privilege is now delegated to MyApp.Application.
• Domain and web libraries are split apart in /lib as /lib/myapp and /lib/myapp_web.
• Tests for myapp_web are moved into /test/myapp_web.

This might not sound like much, but many files will be affected and/or relocated. Here’s a high-level overview of my process for making these updates:

• Use sed to update all references to the MyApp.Web module to MyAppWeb. Be careful not to include your git repo files when using sed destructively. I just grepped for the files containing MyApp.Web and sed-replaced them in batches per-directory with:

sed -i -e 's/MyApp\.Web/MyAppWeb/g' *.ex *.exs

• Move your former /lib/myapp/web directory one level down, into /lib:

git mv lib/myapp/web/ lib/myapp_web

• Move endpoint.ex from /lib/myapp to /lib/myapp_web:

git mv lib/myapp/endpoint.ex lib/myapp_web/endpoint.ex`

• Move web.ex into /lib as the top-level MyAppWeb module definition:

git mv lib/myapp_web/web.ex lib/myapp_web.ex

• Update the template root path in the new /lib/myapp_web.ex file to reflect the new directory structure:

# original 1.3-rc:
  def view do
    quote do
      use Phoenix.View, root: "lib/myapp/web/templates", pattern: "**/*",

# updated 1.3.x (1.3.0, 1.3.1, and 1.3.2):
  def view do
    quote do
      use Phoenix.View, root: "lib/myapp_web/templates", pattern: "**/*",

• Move the application definition at /lib/myapp_web/myapp.ex to /lib/myapp/application.ex:

git mv lib/myapp_web/myapp.ex lib/myapp/application.ex

• Update module name in the application file from MyApp to MyApp.Application:

# /lib/myapp/application.ex

# original 1.3-rc:
defmodule MyApp do
  use Application
  # ...
end

# updated for 1.3.x (1.3.0, 1.3.1 or 1.3.2):
defmodule MyApp.Application do
   use Application
   # ...
end

• Update the application module name in mix.exs:

# /mix.exs

# original 1.3-rc:
  def application do
    [ mod: {MyApp, []},

# updated for 1.3.x (1.3.0, 1.3.1 or 1.3.2)
  def application do
    [ mod: {MyApp.Application, []},

• Generate a new top-level module definition file at /lib/myapp.ex:

# This module was previous populated with the app code that we just extracted
# into MyApp.Application, so there isn't necessarily any additional code here unless
# you've added non-application code to the module:

# /lib/myapp.ex

defmodule MyApp do
end 

• Update the live-reload patterns in your dev env config to reflect the changes. For example:

       # /config/dev.exs

       # original 1.3-rc
      ~r{lib/myapp/web/views/.*(ex)$},
      ~r{lib/myapp/web/templates/.*(eex|haml|slim|slime)$}

       # updated for 1.3.x (1.3.0, 1.3.1 or 1.3.2):
      ~r{lib/myapp_web/views/.*(ex)$},
      ~r{lib/myapp_web/templates/.*(eex|haml|slim|slime)$}

• Move your web-related tests into /test/myapp_web. I previously had the tests for my views and controllers at /test/views and /test/controllers respectively, so I just moved them into a new myapp_web directory:

mkdir test/myapp_web
git mv test/views test/myapp_web
git mv test/controllers test/myapp_web

Finally I just updated the Phoenix version reference in mix.exs to 1.3.1 and did mix do: deps.get, compile, test, and everything worked correctly. I then took step further and updated my Phoenix dependencies to 1.3.2 and had no issues.

I believe this should be all of the necessary steps, but if I’ve missed anything, or any of this looks incorrect, please let me know and I’ll update the guide here.

Thanks,
Mike

Note: This post originally stated that this structual difference was a discrepancy between 1.3.0 and 1.3.1, when in fact it was a change made between the releases of 1.3-rc and 1.3.0. Thanks to @chrismccord for offering this clarification.