In this tutorial, I'll show you how we can use the power of React and Phoenix to create a feed application which will update itself in real time as we add new feeds to our database.

Introduction

Elixir is known for its stability and real-time features, and Phoenix leverages the Erlang VM ability to handle millions of connections alongside Elixir's beautiful syntax and productive tooling. This will help us in generating the real-time updating of data through APIs which would be consumed by our React application to show the data on the user interface.

Getting Started

You should have Elixir, Erlang, and Phoenix installed. More about that can be found on the Phoenix framework's website. Apart from that, we will be using a bare-bones React boilerplate since it's well-maintained and properly documented.

Making the APIs Ready

In this section, we will bootstrap our Phoenix API-only application and add channels to update the APIs in real time. We will just be working with a feed (it will contain a title and a description), and once its value is changed in the database, the API will send the updated value to our front-end application.

Bootstrap the App

Let's first bootstrap the Phoenix application.

mix phoenix.new  realtime_feed_api --no-html --no-brunch

This will create a bare-bones Phoenix application inside a folder named realtime_feed_api. The --no-html option won't create all the static files (which is useful if you're creating an API-only application), and the --no-brunch option won't include Phoenix's static bundler, Brunch. Please make sure you install the dependencies when it prompts.

Let's go inside the folder and create our database.

cd realtime_feed_api

We will have to remove the username and password fields from our config/dev.exs file since we will be creating our database without any username or password. This is just to keep things simple for this post. For your application, make sure that you create a database first, with a username and password.

mix ecto.create

The above command will create our database. Now, we can run our Phoenix server and test if everything is fine at this point.

mix phoenix.server

The above command will fire our Phoenix server, and we can go to http://localhost:4000 to see it running. Currently, it will throw a no route found error since we haven't created any routes yet!

Feel free to verify your changes with my commit.

Add the Feed Model

In this step, we will add our Feed model to our Phoenix app. The Feeds model will consist of a title and a description.

mix phoenix.gen.json Feed feeds title:string description:string

The above command will generate our Feed model and controller. It will also generate the specs (which we won't be modifying in this tutorial, just to keep it short).

You need to add the /feeds route in your web/router.ex file inside the api scope:

resources "/feeds", FeedController, except: [:new, :edit]

We would also need to run the migration to create the feeds table in our database:

mix ecto.migrate

Now, if we go to http://localhost:4000/api/feeds, we will see that the API is sending us a blank response since there is no data in our feeds table.

You can check my commit for reference.

Add the Feed Channel

In this step, we will add our Feed channel to our Phoenix app. Channels provide a means for bidirectional communication from clients that integrate with the Phoenix.PubSub layer for soft real-time functionality.

mix phoenix.gen.channel feed

The above command will generate a feed_channel.ex file inside the web/channels folder. Through this file, our React application will exchange the updated data from the database using sockets.

We need to add the new channel to our web/channels/user_socket.ex file:

channel "feeds", RealtimeFeedApi.FeedChannel

Since we are not doing any authentication for this application, we can modify our web/channels/feed_channel.ex file. We will need one join method for our React application to join our feed channel, one handle_out method to push the payload through a socket connection, and one broadcast_create method which will broadcast a payload whenever a new feed is created in the database.

def join("feeds", payload, socket) do
  {:ok, "Joined feeds", socket}
end

def handle_out(event, payload, socket) do
  push socket, event, payload
  {:noreply, socket}
end

def broadcast_create(feed) do
  payload = %{
    "id" => to_string(feed.id),
    "title" => feed.title,
    "description" => feed.description
  }

  RealtimeFeedApi.Endpoint.broadcast("feeds", "app/FeedsPage/HAS_NEW_FEEDS", payload)
end

The three methods are defined above. In the broadcast_create method, we are using app/FeedsPage/HAS_NEW_FEEDS since we will be using that as a constant for our Redux state container, which will be responsible for letting the front-end application know that there are new feeds in the database. We will discuss that when we build our front-end application.

In the end, we will only need to call the broadcast_change method through our feed_controller.ex file whenever new data is inserted in our create method. Our create method will look something like:

def create(conn, %{"feed" => feed_params}) do
  changeset = Feed.changeset(%Feed{}, feed_params)

  case Repo.insert(changeset) do
    {:ok, feed} ->
      RealtimeFeedApi.FeedChannel.broadcast_create(feed)

      conn
      |> put_status(:created)
      |> put_resp_header("location", feed_path(conn, :show, feed))
      |> render("show.json", feed: feed)
    {:error, changeset} ->
      conn
      |> put_status(:unprocessable_entity)
      |> render(RealtimeFeedApi.ChangesetView, "error.json", changeset: changeset)
  end
end

The create method is responsible for inserting a new data in the database. You can check my commit for reference.

Add CORS Support for the API

We need to implement this support since, in our case, the API is served from http://localhost:4000 but our front-end application will be running on http://localhost:3000. Adding CORS support is easy. We will just need to add cors_plug to our mix.exs file:

defp deps do
  [
   ...
   {:cors_plug, "~> 1.3"}
  ]
end

Now, we stop our Phoenix server using Control-C and fetch the dependency using the following command:

mix deps.get

We will need to add the following line to our lib/realtime_feed_api/endpoint.ex file:

plug CORSPlug

You can check my commit. We are done with all our back-end changes. Let's now focus on the front-end application.

Update the Front-End Data in Real Time

As mentioned earlier, we will use react-boilerplate to get started with our front-end application. We will use Redux saga which will listen to our dispatched actions, and based on that, the user interface will update the data. 

Since everything is already configured in the boilerplate, we don't have to configure it. However, we will make use of the commands available in the boilerplate to scaffold our application. Let's first clone the repository:

git clone https://github.com/react-boilerplate/react-boilerplate.git realtime_feed_ui

Bootstrap the App

Now, we will need to go inside the realtime_feed_ui folder and install the dependencies.

cd realtime_feed_ui && npm run setup

This initializes a new project with this boilerplate, deletes the react-boilerplate git history, installs the dependencies, and initializes a new repository.

Now, let's delete the example app which is provided by the boilerplate, and replace it with the smallest amount of boilerplate code necessary to start writing our app:

npm run clean

We can now start our application using npm run start and see it running at http://localhost:3000/.

You can refer to my commit.

Add the Necessary Containers

In this step, we will add two new containers, FeedsPage and AddFeedPage, to our app. The FeedsPage container will show a list of feeds, and the AddFeedPage container will allow us to add a new feed to our database. We will use the react-boilerplate generators to create our containers.

npm run generate container

The above command is used to scaffold a container in our app. After you type this command, it will ask for the name of the component, which will be FeedsPage in this case, and we will use the Component option in the next step. We won't be needing headers, but we will need actions/constants/selectors/reducer as well as sagas for our asynchronous flows. We don't need i18n messages for our application. We will also need to follow a similar approach to create our AddFeedPage container.

Now, we have a bunch of new files to work with. This saves us a lot of time. Otherwise, we would have to create and configure all these files by ourselves. Also, the generator creates test files, which are very useful, but we won't be writing tests as part of this tutorial.

Let's just quickly add our containers to our routes.js file:

{
  path: '/feeds',
  name: 'feedsPage',
  getComponent(nextState, cb) {
    const importModules = Promise.all([
      import('containers/FeedsPage/reducer'),
      import('containers/FeedsPage/sagas'),
      import('containers/FeedsPage'),
    ]);

    const renderRoute = loadModule(cb);

    importModules.then(([reducer, sagas, component]) => {
      injectReducer('feedsPage', reducer.default);
      injectSagas(sagas.default);

      renderRoute(component);
    });

    importModules.catch(errorLoading);
  },
}

This will add our FeedsPage container to our /feeds route. We can verify this by visiting http://localhost:3000/feeds. Currently, it will be totally blank since we don't have anything in our containers, but there won't be any errors in the console of our browser.

We will do the same for our AddFeedPage container.

You can refer to my commit for all the changes.

Build the Feeds Listing Page

In this step we will build the FeedsPage which will list all our feeds. For the sake of keeping this tutorial small, we won't be adding any styles here, but at the end of our application, I'll make a separate commit which will add some designs to our application.

Let's start by adding our constants in our app/containers/FeedsPage/constants.js file:

export const FETCH_FEEDS_REQUEST = 'app/FeedsPage/FETCH_FEEDS_REQUEST';
export const FETCH_FEEDS_SUCCESS = 'app/FeedsPage/FETCH_FEEDS_SUCCESS';
export const FETCH_FEEDS_ERROR = 'app/FeedsPage/FETCH_FEEDS_ERROR';
export const HAS_NEW_FEEDS = 'app/FeedsPage/HAS_NEW_FEEDS';

We will need these four constants:

• The FETCH_FEEDS_REQUEST constant will be used to initialize our fetching request.
• The FETCH_FEEDS_SUCCESS constant will be used when the fetching request is successful.
• The FETCH_FEEDS_ERROR constant will be used when the fetching request is unsuccessful.
• The HAS_NEW_FEEDS constant will be used when there is a new feed in our database.

Let's add our actions in our app/containers/FeedsPage/actions.js file:

export const fetchFeedsRequest = () => ({
  type: FETCH_FEEDS_REQUEST,
});

export const fetchFeeds = (feeds) => ({
  type: FETCH_FEEDS_SUCCESS,
  feeds,
});

export const fetchFeedsError = (error) => ({
  type: FETCH_FEEDS_ERROR,
  error,
});

export const checkForNewFeeds = () => ({
  type: HAS_NEW_FEEDS,
});

All these actions are self-explanatory. Now, we will structure the initialState of our application and add a reducer in our app/containers/FeedsPage/reducer.js file:

const initialState = fromJS({
  feeds: {
    data: List(),
    ui: {
      loading: false,
      error: false,
    },
  },
  metadata: {
    hasNewFeeds: false,
  },
});

This will be the initialState of our application (the state before the fetching of the data starts). Since we are using ImmutableJS, we can use its List data structure to store our immutable data. Our reducer function will be something like the following:

function addFeedPageReducer(state = initialState, action) {
  switch (action.type) {
    case FETCH_FEEDS_REQUEST:
      return state
        .setIn(['feeds', 'ui', 'loading'], true)
        .setIn(['feeds', 'ui', 'error'], false);
    case FETCH_FEEDS_SUCCESS:
      return state
        .setIn(['feeds', 'data'], action.feeds.data)
        .setIn(['feeds', 'ui', 'loading'], false)
        .setIn(['metadata', 'hasNewFeeds'], false);
    case FETCH_FEEDS_ERROR:
      return state
        .setIn(['feeds', 'ui', 'error'], action.error)
        .setIn(['feeds', 'ui', 'loading'], false);
    case HAS_NEW_FEEDS:
      return state
        .setIn(['metadata', 'hasNewFeeds'], true);
    default:
      return state;
  }
}

Basically, what we are doing here is changing our state based on the constant from our actions. We can show loaders and error messages very easily in this manner. It will be much clearer when we use this in our user interface.

It's time to create our selectors using reselect, which is a selector library for Redux. We can extract complex state values very easily using reselect. Let's add the following selectors to our app/containers/FeedsPage/selectors.js file:

const feeds = () => createSelector(
  selectFeedsPageDomain(),
  (titleState) => titleState.get('feeds').get('data')
);

const error = () => createSelector(
  selectFeedsPageDomain(),
  (errorState) => errorState.get('feeds').get('ui').get('error')
);

const isLoading = () => createSelector(
  selectFeedsPageDomain(),
  (loadingState) => loadingState.get('feeds').get('ui').get('loading')
);

const hasNewFeeds = () => createSelector(
  selectFeedsPageDomain(),
  (newFeedsState) => newFeedsState.get('metadata').get('hasNewFeeds')
);

As you can see here, we are using the structure of our initialState to extract data from our state. You just need to remember the syntax of reselect.

It's time to add our sagas using redux-saga. Here, the basic idea is that we need to create a function to fetch data and another function to watch the initial function so that whenever any specific action is dispatched, we need to call the initial function. Let's add the function which will fetch our list of feeds from the back-end application in our app/containers/FeedsPage/sagas.js file:

function* getFeeds() {
  const requestURL = 'http://localhost:4000/api/feeds';

  try {
    // Call our request helper (see 'utils/Request')
    const feeds = yield call(request, requestURL);
    yield put(fetchFeeds(feeds));
  } catch (err) {
    yield put(fetchFeedsError(err));
  }
}

Here, request is just a util function which does our API call to our back end. The whole file is available at react-boilerplate. We will make a slight change in it after we complete our sagas.js file.

We also need to create one more function to watch the getFeeds function:

export function* watchGetFeeds() {
  const watcher = yield takeLatest(FETCH_FEEDS_REQUEST, getFeeds);

  // Suspend execution until location changes
  yield take(LOCATION_CHANGE);
  yield cancel(watcher);
}

As we can see here, the getFeeds function will be called when we dispatch the action which contains the FETCH_FEEDS_REQUEST constant.

Now, let's copy the request.js file from react-boilerplate into our application inside the app/utils folder and then modify the request function:

export default function request(url, method = 'GET', body) {
  return fetch(url, {
    headers: {
      'Content-Type': 'application/json',
    },
    method,
    body: JSON.stringify(body),
  })
    .then(checkStatus)
    .then(parseJSON);
}

I've just added a few defaults which will help us in reducing the code later on since we don't need to pass the method and headers every time. Now, we need to create another util file inside the app/utils folder. We will call this file socketSagas.js. It will contain four functions: connectToSocket, joinChannel, createSocketChannel, and handleUpdatedData. 

The connectToSocket function will be responsible for connecting to our back-end API socket. We will use the phoenix npm package. So we will have to install it:

npm install phoenix --save

This will install the phoenix npm package and save it to our package.json file. Our connectToSocket function will look something like the following:

export function* connectToSocket() {
  const socket = new Socket('ws:localhost:4000/socket');
  socket.connect();
  return socket;
}

Next, we define our joinChannel function, which will be responsible for joining a particular channel from our back end. The joinChannel function will have the following contents:

export function* joinChannel(socket, channelName) {
  const channel = socket.channel(channelName, {});
  channel.join()
    .receive('ok', (resp) => {
      console.log('Joined successfully', resp);
    })
    .receive('error', (resp) => {
      console.log('Unable to join', resp);
    });

  return channel;
}

If the joining is successful, we will log 'Joined successfully' just for testing. If there was an error during the joining phase, we will also log that just for debugging purposes.

The createSocketChannel will be responsible for creating an event channel from a given socket.

export const createSocketChannel = (channel, constant, fn) =>
  // `eventChannel` takes a subscriber function
  // the subscriber function takes an `emit` argument to put messages onto the channel
  eventChannel((emit) => {
    const newDataHandler = (event) => {
      console.log(event);
      emit(fn(event));
    };

    channel.on(constant, newDataHandler);

    const unsubscribe = () => {
      channel.off(constant, newDataHandler);
    };

    return unsubscribe;
  });

This function will also be useful if we want to unsubscribe from a particular channel.

The handleUpdatedData will just call an action passed to it as an argument.

export function* handleUpdatedData(action) {
  yield put(action);
}

Now, let's add the rest of the sagas in our app/containers/FeedsPage/sagas.js file. We will create two more functions here: connectWithFeedsSocketForNewFeeds and watchConnectWithFeedsSocketForNewFeeds. 

The connectWithFeedsSocketForNewFeeds function will be responsible for connecting with the back-end socket and checking for new feeds. If there are any new feeds, it will call the createSocketChannel function from the utils/socketSagas.js file, which will create an event channel for that given socket. Our connectWithFeedsSocketForNewFeeds function will contain the following:

function* connectWithFeedsSocketForNewFeeds() {
  const socket = yield call(connectToSocket);
  const channel = yield call(joinChannel, socket, 'feeds');

  const socketChannel = yield call(createSocketChannel, channel, HAS_NEW_FEEDS, checkForNewFeeds);

  while (true) {
    const action = yield take(socketChannel);
    yield fork(handleUpdatedData, action);
  }
}

And the watchConnectWithFeedsSocketForNewFeeds will have the following:

export function* watchConnectWithFeedsSocketForNewFeeds() {
  const watcher = yield takeLatest(FETCH_FEEDS_SUCCESS, connectWithFeedsSocketForNewFeeds);

  // Suspend execution until location changes
  yield take(LOCATION_CHANGE);
  yield cancel(watcher);
}

Now, we will tie everything with our app/containers/FeedsPage/index.js file. This file will contain all our user interface elements. Let's start by calling the prop which will fetch the data from the back end in our componentDidMount:

componentDidMount() {
  this.props.fetchFeedsRequest();
}

This will fetch all the feeds. Now, we need to call the fetchFeedsRequest prop again whenever the hasNewFeeds prop is true (you can refer to our reducer's initialState for the structure of our app):

componentWillReceiveProps(nextProps) {
    if (nextProps.hasNewFeeds) {
      this.props.fetchFeedsRequest();
    }
  }

After this, we just render the feeds in our render function. We will create a feedsNode function with the following contents:

feedsNode() {
  return [...this.props.feeds].reverse().map((feed) => { // eslint-disable-line arrow-body-style
    return (
      <div
        className="col-12"
        key={feed.id}
      >
        <div
          className="card"
          style={{ margin: '15px 0' }}
        >
          <div className="card-block">
            <h3 className="card-title">{ feed.title }</h3>
            <p className="card-text">{ feed.description }</p>
          </div>
        </div>
      </div>
    );
  });
}

And then, we can call this method in our render method:

render() {
  if (this.props.loading) {
    return (
      <div>Loading...</div>
    );
  }

  return (
    <div className="row">
      {this.feedsNode()}
    </div>
  );
}

If we now go to http://localhost:3000/feeds, we will see the following logged in our console:

Joined successfully Joined feeds

This means that our feeds API is working fine, and we have successfully connected our front end with our back-end application. Now, we just need to create a form through which we can enter a new feed.

Feel free to refer to my commit since a lot of stuff went in this commit!

Build the Form to Add a New Feed

In this step, we will be creating a form through which we can add a new feed to our database.

Let's start by adding the constants to our app/containers/AddFeedPage/constants.js file:

export const UPDATE_ATTRIBUTES = 'app/AddFeedPage/UPDATE_ATTRIBUTES';
export const SAVE_FEED_REQUEST = 'app/AddFeedPage/SAVE_FEED_REQUEST';
export const SAVE_FEED_SUCCESS = 'app/AddFeedPage/SAVE_FEED_SUCCESS';
export const SAVE_FEED_ERROR = 'app/AddFeedPage/SAVE_FEED_ERROR';

The UPDATE_ATTRIBUTES constant will be used when we add some text to the input box. All the other constants will be used for saving the feed title and description to our database.

The AddFeedPage container will use four actions: updateAttributes, saveFeedRequest, saveFeed, and saveFeedError. The updateAttributes function will update the attributes of our new feed. It means whenever we type something in the input box of the feed title and description, the updateAttributes function will update our Redux state. These four actions will look something like the following:

export const updateAttributes = (attributes) => ({
  type: UPDATE_ATTRIBUTES,
  attributes,
});

export const saveFeedRequest = () => ({
  type: SAVE_FEED_REQUEST,
});

export const saveFeed = () => ({
  type: SAVE_FEED_SUCCESS,
});

export const saveFeedError = (error) => ({
  type: SAVE_FEED_ERROR,
  error,
});

Next, let's add our reducer functions in app/containers/AddFeedPage/reducer.js file. The initialState will look like the following:

const initialState = fromJS({
  feed: {
    data: {
      title: '',
      description: '',
    },
    ui: {
      saving: false,
      error: null,
    },
  },
});

And the reducer function will look something like:

function addFeedPageReducer(state = initialState, action) {
  switch (action.type) {
    case UPDATE_ATTRIBUTES:
      return state
        .setIn(['feed', 'data', 'title'], action.attributes.title)
        .setIn(['feed', 'data', 'description'], action.attributes.description);
    case SAVE_FEED_REQUEST:
      return state
        .setIn(['feed', 'ui', 'saving'], true)
        .setIn(['feed', 'ui', 'error'], false);
    case SAVE_FEED_SUCCESS:
      return state
        .setIn(['feed', 'data', 'title'], '')
        .setIn(['feed', 'data', 'description'], '')
        .setIn(['feed', 'ui', 'saving'], false);
    case SAVE_FEED_ERROR:
      return state
        .setIn(['feed', 'ui', 'error'], action.error)
        .setIn(['feed', 'ui', 'saving'], false);
    default:
      return state;
  }
}

Next, we will be configuring our app/containers/AddFeedPage/selectors.js file. It will have four selectors: title, description, error, and saving. As the name suggests, these selectors will extract these states from the Redux state and make it available in our container as props.

These four functions will look like the following:

const title = () => createSelector(
  selectAddFeedPageDomain(),
  (titleState) => titleState.get('feed').get('data').get('title')
);

const description = () => createSelector(
  selectAddFeedPageDomain(),
  (titleState) => titleState.get('feed').get('data').get('description')
);

const error = () => createSelector(
  selectAddFeedPageDomain(),
  (errorState) => errorState.get('feed').get('ui').get('error')
);

const saving = () => createSelector(
  selectAddFeedPageDomain(),
  (savingState) => savingState.get('feed').get('ui').get('saving')
);

Next, let's configure our sagas for AddFeedPage container. It will have two functions: saveFeed and watchSaveFeed. The saveFeed function will be responsible for doing the POST request to our API, and it will have the following:

export function* saveFeed() {
  const title = yield select(feedTitle());
  const description = yield select(feedDescription());
  const requestURL = 'http://localhost:4000/api/feeds';

  try {
    // Call our request helper (see 'utils/Request')
    yield put(saveFeedDispatch());
    yield call(request, requestURL, 'POST',
      {
        feed: {
          title,
          description,
        },
      },
    );
  } catch (err) {
    yield put(saveFeedError(err));
  }
}

The watchSaveFeed function will be similar to our previous watch functions:

export function* watchSaveFeed() {
  const watcher = yield takeLatest(SAVE_FEED_REQUEST, saveFeed);

  // Suspend execution until location changes
  yield take(LOCATION_CHANGE);
  yield cancel(watcher);
}

Next, we just need to render the form in our container. To keep things modularized, let's create a sub-component for the form. Create a new file form.js inside our app/containers/AddFeedPage/sub-components folder (the sub-components folder is a new folder which you will have to create). It will contain the form with one input box for the title of the feed and one textarea for the description of the feed. The render method will have the following contents:

render() {
  return (
    <form style={{ margin: '15px 0' }}>
      <div className="form-group">
        <label htmlFor="title">Title</label>
        <input
          type="text"
          className="form-control"
          id="title"
          placeholder="Enter title"
          onChange={this.handleChange}
          name="title"
          value={this.state.title}
        />
      </div>
      <div className="form-group">
        <label htmlFor="description">Description</label>
        <textarea
          className="form-control"
          id="description"
          placeholder="Enter description"
          onChange={this.handleChange}
          name="description"
          value={this.state.description}
        />
      </div>
      <button
        type="button"
        className="btn btn-primary"
        onClick={this.handleSubmit}
        disabled={this.props.saving || !this.state.title || !this.state.description }
      >
        {this.props.saving ? 'Saving...' : 'Save'}
      </button>
    </form>
  );
}

We will create two more functions: handleChange and handleSubmit. The handleChange function is responsible for updating our Redux state whenever we add some text, and the handleSubmit function calls our API to save the data in our Redux state.

The handleChange function has the following:

handleChange(e) {
  this.setState({
    [e.target.name]: e.target.value,
  });
}

And the handleSubmit function will contain the following:

handleSubmit() {
  // doing this will make the component faster
  // since it doesn't have to re-render on each state update
  this.props.onChange({
    title: this.state.title,
    description: this.state.description,
  });

  this.props.onSave();

  this.setState({
    title: '',
    description: '',
  });
}

Here, we are saving the data and then clearing the form values.

Now, back to our app/containers/AddFeedPage/index.js file, we will just render the form we just created.

render() {
  return (
    <div>
      <Form
        onChange={(val) => this.props.updateAttributes(val)}
        onSave={() => this.props.saveFeedRequest()}
        saving={this.props.saving}
      />
    </div>
  );
}

Now, all our coding is complete. Feel free to check my commit if you have any doubts.

Finalizing

We have completed building our application. Now, we can visit http://localhost:3000/feeds/new and add new feeds which will be rendered in real time on http://localhost:3000/feeds. We don't need to refresh the page to see the new feeds. You can also try this by opening http://localhost:3000/feeds on two tabs side by side and test it!

Conclusion

This will be just a sample application to show the real powers of combining Phoenix with React. We use real-time data in most places now, and this might just help you get a feel for developing something like that. I hope that you found this tutorial useful.