README.md in react_on_rails-1.0.3 vs README.md in react_on_rails-1.1.0

- old
+ new

@@ -39,10 +39,12 @@ + [How it Works](#how-it-works) - [Client-Side Rendering vs. Server-Side Rendering](#client-side-rendering-vs-server-side-rendering) - [Building the Bundles](#building-the-bundles) - [Globally Exposing Your React Components](#globally-exposing-your-react-components) - [Rails View Helpers In-Depth](#rails-view-helpers-in-depth) + - [Redux](#redux) + - [React-Router](#react-router) + [Generator](#generator) - [Understanding the Organization of the Generated Client Code](#understanding-the-organization-of-the-generated-client-code) - [Redux](#redux) - [Using Images and Fonts](#using-images-and-fonts) - [Bootstrap Integration](#bootstrap-integration) @@ -92,11 +94,10 @@ ## Getting Started 1. Add the following to your Gemfile and bundle install: ```ruby gem "react_on_rails" - gem "therubyracer" ``` 2. Run the generator with a simple "Hello World" example: ```bash @@ -121,12 +122,14 @@ The generator installs your webpack files in the `client` folder. Foreman uses webpack to compile your code and output the bundled results to `app/assets/javascripts/generated`, which are then loaded by sprockets. These generated bundle files have been added to your `.gitignore` for your convenience. Inside your Rails views, you can now use the `react_component` helper method provided by React on Rails. ### Client-Side Rendering vs. Server-Side Rendering -In most cases, you should use the `prerender: false` (default behavior) with the provided helper method to render the React component from your Rails views. In some cases, such as when SEO is vital or many users will not have JavaScript enabled, you can enable server-rendering by passing `prerender: true` to your helper, or you can simply change the default in `config/initializers/react_on_rails`. Your JavaScript can then be first rendered on the server and passed to the client as HTML. +In most cases, you should use the `prerender: false` (default behavior) with the provided helper method to render the React component from your Rails views. In some cases, such as when SEO is vital or many users will not have JavaScript enabled, you can enable server-rendering by passing `prerender: true` to your helper, or you can simply change the default in `config/initializers/react_on_rails`. +Now the server will interpret your JavaScript using [ExecJS](https://github.com/rails/execjs) and pass the resulting HTML to the client. We recommend using [therubyracer](https://github.com/cowboyd/therubyracer) as ExecJS's runtime. The generator will automatically add it to your Gemfile for you. + Note that **server-rendering requires globally exposing your components by setting them to `global`, not `window`** (as is the case with client-rendering). If using the generator, you can pass the `--server-rendering` option to configure your application for server-side rendering. In the following screenshot you can see the 3 parts of react_on_rails rendering: 1. Inline JavaScript to "client-side" render the React component. @@ -179,12 +182,14 @@ + **react_component_name:** Can be a React component, created using a ES6 class, or `React.createClass`, or a generator function that returns a React component. + **props:** Ruby Hash which contains the properties to pass to the react object, or a JSON string. If you pass a string, we'll escape it for you. + **options:** + **generator_function:** default is false, set to true if you want to use a generator function rather than a React Component. Why would you do this? 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. + **prerender:** enable server-side rendering of component. Set to false when debugging! + + **router_redirect_callback:** Use this option if you want to provide a custom handler for redirects on server rendering. If you don't specify this, we'll simply change the rendered output to a script that sets window.location to the new route. Set this up exactly like a generator_function. Your function will will take one parameter, containing all the values that react-router gives on a redirect request, such as pathname, search, etc. + **trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise. + **replay_console:** Default is true. False will disable echoing server-rendering logs to the browser. While this can make troubleshooting server rendering difficult, so long as you have the default configuration of logging_on_server set to true, you'll still see the errors on the server. + + **raise_on_prerender_error:** Default is false. True will throw an error on the server side rendering. Your controller will have to handle the error. + Any other options are passed to the content tag, including the id #### server_render_js `server_render_js(js_expression, options = {})` @@ -313,9 +318,10 @@ + [Generated Client Code](docs/additional_reading/generated_client_code.md) + [Heroku Deployment](docs/additional_reading/heroku_deployment.md) + [Manual Installation](docs/additional_reading/manual_installation.md) + [Node Dependencies and NPM](docs/additional_reading/node_dependencies_and_npm.md) + [Optional Configuration](docs/additional_reading/optional_configuration.md) ++ [React Router](docs/additional_reading/react_router.md) + [Server Rendering Tips](docs/additional_reading/server_rendering_tips.md) + [Tips](docs/additional_reading/tips.md) ## Contributing Bug reports and pull requests are welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to our version of the [Contributor Covenant](contributor-covenant.org) code of conduct (see [CODE OF CONDUCT](docs/code_of_conduct.md)).