Phoenix Web Framework: The Unauthorized Guide

Is this guide right for me?

Requirements

This guide is suitable for anyone who:

• Has a basic understanding of Elixir
  • You do not need to be an expert, but having a basic knowledge of Elixir syntax is crucial to understand what is happening. Even a few hours or days of study will make a big difference.
  • Resources for installing Elixir:
    • Official Elixir docs: Introduction
    • Official recommendations for learning Elixir
    • Elixir School: Basics
    • Elixir in Action, Third Edition [Book]
• Has Elixir installed on their computer
  • If you can type mix new hello_world into your terminal to generate a new Elixir project, then you have this step covered.
  • Resources for installing Elixir:
    • If you do not have Elixir installed yet, it is recommended to use the asdf version manager to simplify the process of installing Elixir.
    • Official Elixir installation docs
    • Thinking Elixir: Install Elixir using asdf

If you don't meet all the requirements, check out the provided links and come back when you are ready to continue.

Recommendations

The following items are not required to work through this guide, but are strongly recommended to have. They will be referenced at various stages in this guide. Skip these at your own peril.

• Elixir works best in Linux or macOS.
  • If you are using Windows, you may want to install WSL or install Linux on a virtual machine so that you can work through the guide in a Unix-style environment.
  • This is not an essential step, but you may run into more unexpected issues when working with Elixir on Windows, compared to Linux or macOS.
• You should understand the basics of working in a terminal (e.g. Bash, ZSH).
• You should have an adequate code editor installed (e.g. VSCode) and configured for Elixir development.
• You should have Git installed.
  • If you don't know how to use Git, you should learn the basics. It is an essential part of the modern development workflow. You don't need to be an expert: This guide will provide basic examples of its usage when relevant.
    • Tutorial: Basic guide to Git
    • If you need an example Git repo to clone, you can use the project repo for this guide. Just open your terminal, cd to your preferred directory, and run the following command:
      • git clone https://github.com/arcanemachine/phoenix-guide-todo-list
• You should have Docker installed:
  • Docker can be used when building containerized releases of your Elixir/Phoenix application.
• You should have Postgres (a.k.a. PostgreSQL) installed.
  • If you have Docker installed, you can skip this step for now. (This guide contains some brief instructions on using Docker to manage a Postgres instance, which is simpler than having to manage Postgres as a global system applicastion)

What will I learn in this guide?

In this guide, you will learn how to create a basic Phoenix application from start to finish. We will explore all of the basic building blocks used in the Phoenix web framework. You will create a Phoenix web application, add functionality to it, test it, and learn how to deploy the application.

In this guide, we will be creating a todo list called (uninspiringly) TodoList. A todo list is a simple project that allows us to model different types of database relationships (one-to-one, one-to-many, many-to-many), as well as providing us some objects to CRUD (create, read, update, and destroy). It's simple, but covers all the concepts, and is easy to hold in one's head.

Although this guide is about Phoenix, it also makes use of some other Elixir packages that are first-class citizens when working with Phoenix, particularly Ecto, which is an Elixir package that is used to communicate with the database (we'll be using Postgres).

For a full list of all the topics covered in this guide, see the table of contents

A note on Phoenix generators

This guide takes very heavy (often verbatim) inspiration from the Phoenix generators. In many parts of the guide, we will create many parts of the application by manually implementing a lot of material that can be created automatically by using the Phoenix generators.

The Phoenix generators can save a lot of time, but they can also produce an overwhelming amount of files for a newcomer to wrap their mind around. By creating these files manually, we can understand what is happening later on when we use them to create new resources for our project.

Do I need to follow the guide from start to finish?

Nope! This guide (and its companion Git repo) are structured so that you can start from the beginning of whichever chapter you want. The companion repo has a commit for each chapter. Just use Git to clone the repo, switch to the commit for the chapter before the one you want to work on, and dive in!

Tip: The first time you clone the repo, you will need to install the dependencies by running mix deps.get from the repo's main directory.

Why create this guide?

As of the current time of writing, no book currently exists that provides an introduction to Phoenix version 1.7 or greater.

There are books that work for older versions of Phoenix, such as Programming Phoenix and Phoenix in Action, but these books are not suitable for newcomers who want to learn newer versions of Phoenix in a printed format. These books are perfectly adequate learning resources when working with Phoenix 1.6 or below. However, attempting to use the books to learn Phoenix 1.7 or greater is an exercise in frustration due to some of the changes made in Phoenix 1.7. Although the changes are easy to understand if you know how to use Phoenix, they are enough of a departure from the previous instructions to break most guides made for Phoenix 1.6 or below.

There is a more recent book on Phoenix LiveView called Programming Phoenix LiveView, which is a fantastic resource on the subject of LiveView. However, LiveView is one part of Phoenix, and sits on top of the foundation of the other parts of Phoenix, which still deserve a decent guide.

The official Phoenix documentation is currently the most-commonly recommended resource for learning Phoenix 1.7 or greater. It is an excellent resource, but I feel that there is room for something a little more thorough and beginner friendly.

This guide is intended to provide an answer to the question "What book can I read to learn Phoenix?" in the year 2025 and beyond.

Created 2025-02-11. Modified 2025-11-17.