Restructuring Phoenix 1.3-rc apps for 1.3.1, 1.3.2, 1.3.x

Learning Resources Guides/Tuts/Tips/Info
1

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.

11 Likes
2

To be clear, we did not change any structure from 1.3.0 - 1.3.2. I believe you were running an early 1.3 RC version which used the App.Web namespace, and we moved to AppWeb before final release. I’ve updated the title accordingly :slight_smile:

6 Likes
3

Hey there Chris - thanks for the response here. That indeed was the case. I didn’t realize this structure had changed between 1.3-rc and 1.3.0. The clarification is much appreciated. I just quickly revised the references in the examples, but I’ll go through the tutorial tomorrow and update the rest of the language to better reflect this distinction.

4 Likes