Functions to make rendering React.js components easy in Phoenix.
Combined with the javascript also included in this package, rendering React components in your Phoenix views is now much easier. The module was built with Brunch in mind (vs Webpack). Since Phoenix uses Brunch by default, this package can make getting React into your application much faster than switching over to a different system.
Note regarding Phoenix versions < 1.3
This README is written as a guide for Phoenix apps running Phoenix >= 1.3. If you are using a version of Phoenix below version 1.3, you can check out the Phoenix 1.2 README.
This package is meant to be quick and painless to install into your Phoenix application.
The package can be installed by adding react_phoenix
to your list of
dependencies in mix.exs
:
def deps do
[{:react_phoenix, "~> 0.5.1"}]
end
After adding to your mix file, run:
> mix deps.get
In order to correctly render a React component in your view templates, a
provided javascript file must be included in your assets/package.json
file in
the dependencies section. It might look like this:
{
...
"dependencies": {
"phoenix": "file:../deps/phoenix",
"phoenix_html": "file:../deps/phoenix_html",
"react-phoenix": "file:../deps/react_phoenix" <-- ADD THIS!
},
...
}
Then run (from your assets
directory)
> npm install
Since we want React and would like to write JSX in our app, we need to make sure we get the packages brunch needs in order to compile our files.
> npm install react babel-preset-env babel-preset-react --save
We also need to activate those presets from our assets/brunch-config.js
file:
// ...
// Configure your plugins
plugins: {
babel: {
presets: ["env", "react"], // <-- ADD THIS!
// Do not use ES6 compiler in vendor code
ignore: [/vendor/]
}
},
// ...
In your main application javascript file (usually assets/js/app.js
), add the
following line:
import "react-phoenix"
If you'd like to just call react_component(...)
in your views instead of the full
ReactPhoenix.ClientSide.react_component(...)
, you can import ReactPhoenix.ClientSide
into your lib/APPNAME_web.ex
views section. It might look like this:
def view do
quote do
use Phoenix.View, root: "web/templates"
import Phoenix.Controller, only: [get_csrf_token: 0, get_flash: 2, view_module: 1]
use Phoenix.HTML
import MyPhoenixApp.Router.Helpers
import MyPhoenixApp.ErrorHelpers
import MyPhoenixApp.Gettext
import ReactPhoenix.ClientSide # <-- ADD THIS!
end
end
Once installed, you can use react_component
in your views by:
-
Making sure that the component you'd like rendered is in the global namespace. You can do that in
app.js
like this (for example):import MyComponent from "./components/my_component" window.Components = { MyComponent }
-
In your view template, you can then render it like this:
# with no props <%= ReactPhoenix.ClientSide.react_component("Components.MyComponent") %> # with props <%= ReactPhoenix.ClientSide.react_component("Components.MyComponent", %{language: "elixir", awesome: true}) %> # with props and a target html element id option <span id="my-react-span"><%= @react_html %></span> <%= ReactPhoenix.ClientSide.react_component("Components.Characters", %{people: people}, target_id: "my-react-span") %>
This will render a special
div
element in your html output that will then be recognized by the javascript helper as a div that should be turned into a React component. It will then render the named component in thatdiv
(or a different element specified by ID via thetarget_id
option).
Server-side rendering is a bit of a bear to get right with brunch. In fact, there was a previous version
(0.4.3) of
react-phoenix
that included an attempt at server-side rendering. It worked locally for me, but only after many
attempts to get it right. In the end, there was a specific set of hand-wavy things you needed to do to get it working
and I removed all the server-side code from the master branch for now.
I may have some time freed up in the future to attempt to tackle it again. But for the simplicity of installation and usage, client-side rendering is likely all you'll need for now.
This package is heavily inspired by the react-rails project.
For more detailed documentation, check out the hex docs at https://hexdocs.pm/react_phoenix