README.md in react_on_rails-1.1.1 vs README.md in react_on_rails-1.2.0.rc1

- old
+ new

@@ -49,10 +49,11 @@ - [Using Images and Fonts](#using-images-and-fonts) - [Bootstrap Integration](#bootstrap-integration) + [Bootstrap via Rails Server](#bootstrap-via-rails-server) + [Bootstrap via Webpack HMR Dev Server](#bootstrap-via-webpack-hmr-dev-server) + [Keeping Custom Bootstrap Configurations Synced](#keeping-custom-bootstrap-configurations-synced) + + [Skip Bootstrap Integration](#skip-bootstrap-integration) - [Linters](#linters) + [JavaScript Linters](#javascript-linters) + [Ruby Linters](#ruby-linters) + [Running the Linters](#running-the-linters) + [Developing with the Webpack Dev Server](#developing-with-the-webpack-dev-server) @@ -73,29 +74,29 @@ + [Webpack optimization functionality](https://github.com/webpack/docs/wiki/optimization) + _*(Coming Soon)*_ [React Router](https://github.com/rackt/react-router) + *([Gem *Pull Request*](https://github.com/shakacode/react_on_rails/pull/68))* + *([Tutorial Pull Request](https://github.com/shakacode/react-webpack-rails-tutorial/pull/128))* -See the [react-webpack-rails-tutorial](https://github.com/justin808/react-webpack-rails-tutorial/) for an example of a live implementation and code. +See the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) for an example of a live implementation and code. ## Why Webpack? Webpack is used for 2 purposes: 1. Generate several JavaScript "bundles" for inclusion in `application.js`. 2. Providing the Webpack Dev Server for quick prototyping of components without needing to refresh your browser to see updates. -This usage of webpack fits neatly and simply into the existing Rails sprockets system and you can include React components on a Rails view with a simple helper. +This usage of webpack fits neatly and simply into the existing Rails sprockets system and you can include React components on a Rails view with a simple helper. 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. ## Getting Started 1. Add the following to your Gemfile and bundle install: - + ```ruby gem "react_on_rails" ``` 2. Run the generator with a simple "Hello World" example: @@ -126,11 +127,11 @@ ### 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`. 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. +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. 2. The wrapper div `<div id="HelloWorld-react-component-0">` enclosing the server-rendered HTML for the React component @@ -147,32 +148,32 @@ ### Globally Exposing Your React Components 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**. + *Normal Mode (JavaScript is Rendered on client):* - + If you are not server rendering, `clientGlobals.jsx` will have - + ```javascript window.HelloWorldApp = HelloWorldApp; ``` + *Server-Side Rendering:* If you are server rendering, `globals.jsx` will have: - + ```javascript window.HelloWorldApp = HelloWorldAppClient; ``` - + `serverGlobals.jsx` will have: - + ```javascript global.HelloWorldApp = HelloWorldAppServer; ``` - + In general, you want different initialization for your server rendered components. - + ### Rails View Helpers In-Depth Once the bundled files have been generated in your `app/assets/javascripts/generated` folder and you have exposed your components globally, you will want to run your code in your Rails views using the included helper method. This is how you actually render the React components you exposed to `window` inside of `clientGlobals` (and `global` inside of `serverGlobals` if you are server rendering). @@ -211,10 +212,11 @@ -R, [--redux], [--no-redux] # Install Redux gems and Redux version of Hello World Example -S, [--server-rendering], [--no-server-rendering] # Add necessary files and configurations for server-side rendering -j, [--skip-js-linters], [--no-skip-js-linters] # Skip installing JavaScript linting files -L, [--ruby-linters], [--no-ruby-linters] # Install ruby linting files, tasks, and configs -H, [--heroku-deployment], [--no-heroku-deployment] # Install files necessary for deploying to Heroku + -b, [--skip-bootstrap], [--no-skip-bootstrap] # Skip installing files for bootstrap support Runtime options: -f, [--force] # Overwrite files that already exist -p, [--pretend], [--no-pretend] # Run but do not make any changes -q, [--quiet], [--no-quiet] # Suppress status output @@ -222,11 +224,11 @@ Description: Create react on rails files for install generator. ``` -For a clear example of what each generator option will do, see our generator results repo: [Generator Results](https://github.com/shakacode/react_on_rails-generator-results-1-0-0/pulls). Each pull request shows a git "diff" that highlights the changes that the generator has made. +For a clear example of what each generator option will do, see our generator results repo: [Generator Results](https://github.com/shakacode/react_on_rails-generator-results/pulls). Each pull request shows a git "diff" that highlights the changes that the generator has made. ### Understanding the Organization of the Generated Client Code The generated client code follows our organization scheme. Each unique set of functionality, is given its own folder inside of `client/app/bundles`. This encourages for modularity of DOMAINS. Inside of the generated "HelloWorld" domain you will find the following folders: @@ -236,11 +238,11 @@ + `components`: includes "dumb components", or components that simply render their properties and call functions given to them as properties by a parent component. Ultimately, at least one of these dumb components will have a parent container component. You may also notice the `app/lib` folder. This is for any code that is common between bundles and therefore needs to be shared (for example, middleware). ### Redux -If you have used the `--redux` generator option, you will notice the familiar additional redux folders in addition to the aforementioned folders. The Hello World example has also been modified to use Redux. +If you have used the `--redux` generator option, you will notice the familiar additional redux folders in addition to the aforementioned folders. The Hello World example has also been modified to use Redux. Note the organizational paradigm of "bundles". These are like application domains and are used for grouping your code into webpack bundles, in case you decide to create different bundles for deployment. This is also useful for separating out logical parts of your application. The concept is that each bundle will have it's own Redux store. If you have code that you want to reuse across bundles, including components and reducers, place them under `/client/app/lib`. ### Using Images and Fonts The generator has amended the folders created in `client/assets/` to Rails's asset path. We recommend that if you have any existing assets that you want to use with your client code, you should move them to these folders and use webpack as normal. This allows webpack's development server to have access to your assets, as it will not be able to see any assets in the default Rails directories which are above the `/client` directory. @@ -261,10 +263,13 @@ When using the webpack dev server, which does not go through Rails, bootstrap is loaded via the [bootstrap-sass-loader](https://github.com/shakacode/bootstrap-sass-loader) which uses the `client/bootstrap-sass-config.js` file. #### Keeping Custom Bootstrap Configurations Synced Because the webpack dev server and Rails each load Bootstrap via a different file (explained in the two sections immediately above), any changes to the way components are loaded in one file must also be made to the other file in order to keep styling consistent between the two. For example, if an import is excluded in `_bootstrap-custom.scss`, the same import should be excluded in `bootstrap-sass-config.js` so that styling in the Rails server and the webpack dev server will be the same. +#### Skip Bootstrap Integration +Bootstrap integration is enabled by default, but can be disabled by passing the `--skip-bootstrap` flag (alias `-b`). When you don't need Bootstrap in your existing project, just skip it as needed. + ### Linters The React on Rails generator can add linters and their recommended accompanying configurations to your project. There are two classes of linters: ruby linters and JavaScript linters. ##### JavaScript Linters JavaScript linters are **enabled by default**, but can be disabled by passing the `--skip-js-linters` flag (alias `j`) , and those that run in Node have been add to `client/package.json` under `devDependencies`. @@ -317,14 +322,15 @@ ## Additional Reading + [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) ++ [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) ++ [Webpack Configuration](docs/additional_reading/webpack.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)). See [Contributing](docs/contributing.md) to get started. @@ -345,10 +351,10 @@ And based on the work of the [react-rails gem](https://github.com/reactjs/react-rails) ## About [ShakaCode](http://www.shakacode.com/) -Visit [our forums!](http://forum.shakacode.com). We've got a [category dedicated to react_on_rails](http://forum.shakacode.com/c/rails/reactonrails). +Visit [our forums!](http://forum.shakacode.com). We've got a [category dedicated to react_on_rails](http://forum.shakacode.com/c/rails/reactonrails). If you're looking for consulting on a project using React and Rails, email us ([contact@shakacode.com](mailto: contact@shakacode.com))! You can also join our slack room for some free advice. We're looking for great developers that want to work with Rails + React with a distributed, worldwide team, for our own products, client work, and open source. [More info here](http://www.shakacode.com/about/index.html#work-with-us).