README.md in react_on_rails-7.1.0.beta.2 vs README.md in react_on_rails-7.1.0.beta.3
- old
+ new
@@ -1,10 +1,10 @@
[](https://travis-ci.org/shakacode/react_on_rails) [](https://app.codeship.com/projects/187011) [](https://gemnasium.com/shakacode/react_on_rails) [](https://badge.fury.io/rb/react_on_rails) [](https://badge.fury.io/js/react-on-rails) [](https://codeclimate.com/github/shakacode/react_on_rails) [](https://coveralls.io/github/shakacode/react_on_rails?branch=master)
**For a complete example of this gem, see our live demo at [www.reactrails.com](http://www.reactrails.com). ([Source Code](https://github.com/shakacode/react-webpack-rails-tutorial))**
-**Speaking!**: Justin is speaking [GORUCO](http://goruco.com/#speakers) on Saturday, June 24, 2017 in NYC: "Front-End Sadness to Happiness: The React on Rails Story". [Email Justin](mailto:justin@shakacode.com) to give this talk at your local meetup or company. [Subscribe](https://app.mailerlite.com/webforms/landing/l1d9x5) to be notified of local and *online* presentations of this talk.
+**Speaking!**: Justin is speaking [GORUCO](http://goruco.com/#speakers) on Saturday, June 24, 2017 in NYC: "Front-End Sadness to Happiness: The React on Rails Story". [Email Justin](mailto:justin@shakacode.com) to give this talk at your local meetup or company. [Subscribe](https://app.mailerlite.com/webforms/landing/l1d9x5) to be notified of local and *online* presentations of this talk.
**Aloha from Justin Gordon** ([bio](http://www.railsonmaui.com/about)) and the [ShakaCode](http://www.shakacode.com) Team! We're actively looking for new projects involving React, React-Native, and Rails, including conversion of AngularJs to React. Please [contact me](mailto:justin@shakacode.com) if we could potentially help you in any way. Besides consulting on bigger projects, [ShakaCode](http://www.shakacode.com) is doing ScreenHero plus Slack/Github based [coaching](http://www.shakacode.com/work/shakacode-coaching-plan.pdf) for React on Rails. See our blog post [Can ShakaCode Help You?](https://blog.shakacode.com/can-shakacode-help-you-4a5b1e5a8a63#.jex6tg9w9) for more information.
I'm offering a free half-hour project consultation, on anything from React on Rails to any aspect of web application development for both consumer and enterprise products. In addition to React.js and Rails, we're doing React-Native iOS and Android apps!
@@ -47,11 +47,11 @@
### Podcasts
* [284 Ruby Rogues: React on Rails with Justin Gordon and Rob Wise](https://devchat.tv/ruby-rogues/284-rr-react-on-rails-with-justin-gordon-and-rob-wise)
# NEWS
-* 2017-04-25: 7.0.0 Shipped! Performance improvements! Please upgrade! Only "breaking" change is that you have to update both the node module and the Ruby gem.
+* 2017-04-25: 7.0.0 Shipped! Performance improvements! Please upgrade! Only "breaking" change is that you have to update both the node module and the Ruby gem.
* 2017-04-09: 8.0.0 beta work to include webpacker_lite gem has begun. See [#786](https://github.com/shakacode/react_on_rails/issues/786).
* *See [NEWS.md](NEWS.md) for more notes over time.*
# React on Rails
@@ -104,18 +104,22 @@
Compare this to some alternative approaches for SPAs (Single Page Apps) that utilize Webpack and Rails. They will use a separate node server to distribute web pages, JavaScript assets, CSS, etc., and will still use Rails as an API server. A good example of this is our ShakaCode team member Alex's article [
Universal React with Rails: Part I](https://medium.com/@alexfedoseev/isomorphic-react-with-rails-part-i-440754e82a59).
We're definitely not doing that. With react_on_rails, webpack is mainly generating a nice JavaScript file for inclusion into `application.js`. We're going to KISS. And that's all relative given how much there is to get right in an enterprise class web application.
+## Upgrade
+
+To upgrade existing apps to react on rails 7 see the [Installation Overview](docs/basics/installation-overview.md)
+
## Getting Started
**For more detailed instructions**, see the [React on Rails Basic Tutorial](docs/tutorial.md).
1. Add the following to your Gemfile and `bundle install`.
```ruby
- gem "react_on_rails", "~> 6"
+ gem "react_on_rails", "~> 7"
```
2. Commit this to git (you cannot run the generator unless you do this or pass the option `--ignore-warnings`).
3. See help for the generator:
@@ -142,13 +146,13 @@
```bash
foreman start -f Procfile.dev
```
-8. Visit [localhost:5000/hello_world](http://localhost:5000/hello_world). Note, `foreman` defaults to PORT 5000 unless you set the value of PORT in your environment. For example, you can `export PORT=3000` to use the Rails default port of 3000.
+8. Visit [localhost:3000/hello_world](http://localhost:3000/hello_world). Note, `foreman` defaults to PORT 5000 unless you set the value of PORT in your environment. For example, you can `export PORT=3000` to use the Rails default port of 3000. For the hello_world example this is already set.
-### Installation Summary
+### Installation Overview
See the [Installation Overview](docs/basics/installation-overview.md) for a concise set summary of what's in a React on Rails installation.
### Initializer Configuration
@@ -157,33 +161,33 @@
### Including your React Component in your Rails Views
+ *Normal Mode (React component will be rendered on client):*
```erb
- <%= react_component("HelloWorldApp", props: @some_props) %>
+ <%= react_component("HelloWorld", props: @some_props) %>
```
+ *Server-Side Rendering (React component is first rendered into HTML on the server):*
```erb
- <%= react_component("HelloWorldApp", props: @some_props, prerender: true) %>
+ <%= react_component("HelloWorld", props: @some_props, prerender: true) %>
```
-+ The `component_name` parameter is a string matching the name you used to expose your React component globally. So, in the above examples, if you had a React component named "HelloWorldApp," you would register it with the following lines:
++ The `component_name` parameter is a string matching the name you used to expose your React component globally. So, in the above examples, if you had a React component named "HelloWorld," you would register it with the following lines:
```js
import ReactOnRails from 'react-on-rails';
- import HelloWorldApp from './HelloWorldApp';
- ReactOnRails.register({ HelloWorldApp });
+ import HelloWorld from './HelloWorld';
+ ReactOnRails.register({ HelloWorld });
```
Exposing your component in this way is how React on Rails is able to reference your component from a Rails view. You can expose as many components as you like, as long as their names do not collide. See below for the details of how you expose your components via the react_on_rails webpack configuration.
+ `@some_props` can be either a hash or JSON string. This is an optional argument assuming you do not need to pass any options (if you want to pass options, such as `prerender: true`, but you do not want to pass any properties, simply pass an empty hash `{}`). This will make the data available in your component:
```ruby
# Rails View
- <%= react_component("HelloWorldApp", props: { name: "Stranger" }) %>
+ <%= react_component("HelloWorld", props: { name: "Stranger" }) %>
```
```javascript
// inside your React component
this.props.name // "Stranger"
@@ -220,11 +224,11 @@
1. A hidden HTML div that contains the properties of the React component, such as the registered name and any props. A JavaScript function runs after the page loads to convert take this data and build initialize React components.
2. The wrapper div `<div id="HelloWorld-react-component-0">` specifies the div where to place the React rendering. It encloses the server-rendered HTML for the React component
3. Additional JavaScript is placed to console log any messages, such as server rendering errors. Note, these server side logs can be configured to only be sent to the server logs.
-**Note**:
+**Note**:
* If server rendering is not used (prerender: false), then the major difference is that the HTML rendered for the React component only contains the outer div: `<div id="HelloWorld-react-component-0"/>`. The first specification of the React component is just the same.
* The below image is not yet updated for version 7.0.0 which uses a `<script>` tag for the props. Instead of a hidden div, we have the props inside of the a `<script>` tag.
@@ -321,20 +325,20 @@
Place your JavaScript code inside of the provided `client/app` folder. Use modules just as you would when using webpack alone. The difference here is that instead of mounting React components directly to an element using `React.render`, you **expose your components globally and then mount them with helpers inside of your Rails views**.
This is an example of how to expose a component to the `react_component` view helper.
```javascript
- // client/app/bundles/HelloWorld/startup/HelloWorldApp.jsx
+ // client/app/bundles/HelloWorld/startup/HelloWorld.jsx
import HelloWorld from '../components/HelloWorld';
import ReactOnRails from 'react-on-rails';
ReactOnRails.register({ HelloWorld });
```
#### Different Server-Side Rendering Code (and a Server Specific Bundle)
You may want different initialization for your server rendered components. For example, if you have animation that runs when a component is displayed, you might need to turn that off when server rendering. However, the `railsContext` will tell you if your JavaScript code is running client side or server side. So code that required a different server bundle previously may no longer require this!
-If you do want different code to run, you'd setup a separate webpack compilation file and you'd specify a different, server side entry file. ex. 'serverHelloWorldApp.jsx'. Note, you might be initializing HelloWorld with version specialized for server rendering.
+If you do want different code to run, you'd setup a separate webpack compilation file and you'd specify a different, server side entry file. ex. 'serverHelloWorld.jsx'. Note, you might be initializing HelloWorld with version specialized for server rendering.
#### Generator Functions
Why would you create a function that returns a React component? For example, you may want the ability to use the passed-in props to initialize a redux store or setup react-router. Or you may want to return different components depending on what's in the props. ReactOnRails will automatically detect a registered generator function.
Another reason to use a generator function is that sometimes in server rendering, specifically with React Router, you need to return the result of calling ReactDOMServer.renderToString(element). You can do this by returning an object with the following shape: { renderedHtml, redirectLocation, error }.