react_on_rails 10.0.0 → 11.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. checksums.yaml +4 -4
  2. data/.eslintrc +4 -0
  3. data/.rubocop.yml +2 -2
  4. data/.travis.yml +3 -0
  5. data/CHANGELOG.md +81 -88
  6. data/CONTRIBUTING.md +0 -7
  7. data/Dockerfile_tests +12 -0
  8. data/Gemfile +8 -13
  9. data/NEWS.md +2 -0
  10. data/PROJECTS.md +10 -2
  11. data/README.md +137 -121
  12. data/app/helpers/react_on_rails_helper.rb +1 -533
  13. data/docker-compose.yml +11 -0
  14. data/docs/additional-reading/caching-and-performance.md +4 -0
  15. data/docs/additional-reading/capistrano-deployment.md +18 -0
  16. data/docs/additional-reading/elastic-beanstalk.md +53 -33
  17. data/docs/additional-reading/server-rendering-tips.md +4 -4
  18. data/docs/additional-reading/troubleshooting-when-using-webpacker.md +90 -0
  19. data/docs/api/ruby-api.md +7 -2
  20. data/docs/basics/configuration.md +23 -9
  21. data/docs/basics/i18n.md +4 -0
  22. data/docs/basics/upgrading-react-on-rails.md +181 -0
  23. data/docs/tutorial.md +7 -11
  24. data/lib/generators/react_on_rails/base_generator.rb +6 -3
  25. data/lib/generators/react_on_rails/dev_tests_generator.rb +1 -1
  26. data/lib/generators/react_on_rails/install_generator.rb +1 -1
  27. data/lib/generators/react_on_rails/react_no_redux_generator.rb +1 -1
  28. data/lib/generators/react_on_rails/react_with_redux_generator.rb +2 -2
  29. data/lib/generators/react_on_rails/templates/base/base/app/javascript/bundles/HelloWorld/components/HelloWorld.jsx +1 -1
  30. data/lib/generators/react_on_rails/templates/base/base/config/initializers/react_on_rails.rb +3 -2
  31. data/lib/generators/react_on_rails/templates/dev_tests/spec/simplecov_helper.rb +2 -2
  32. data/lib/react_on_rails/assets_precompile.rb +8 -4
  33. data/lib/react_on_rails/configuration.rb +34 -20
  34. data/lib/react_on_rails/error.rb +4 -0
  35. data/lib/react_on_rails/locales_to_js.rb +2 -2
  36. data/lib/react_on_rails/prerender_error.rb +2 -2
  37. data/lib/react_on_rails/react_on_rails_helper.rb +547 -0
  38. data/lib/react_on_rails/server_rendering_pool/{exec.rb → ruby_embedded_java_script.rb} +37 -40
  39. data/lib/react_on_rails/server_rendering_pool.rb +21 -10
  40. data/lib/react_on_rails/test_helper/webpack_assets_status_checker.rb +2 -2
  41. data/lib/react_on_rails/test_helper.rb +1 -1
  42. data/lib/react_on_rails/utils.rb +14 -52
  43. data/lib/react_on_rails/version.rb +1 -1
  44. data/lib/react_on_rails/version_checker.rb +33 -12
  45. data/lib/react_on_rails/webpacker_utils.rb +42 -0
  46. data/lib/react_on_rails.rb +3 -2
  47. data/package.json +2 -5
  48. data/rakelib/dummy_apps.rake +2 -1
  49. data/rakelib/example_type.rb +1 -1
  50. data/rakelib/examples.rake +3 -2
  51. data/rakelib/lint.rake +3 -2
  52. data/rakelib/node_package.rake +2 -1
  53. data/rakelib/release.rake +4 -5
  54. data/rakelib/run_rspec.rake +3 -4
  55. data/rakelib/task_helpers.rb +1 -1
  56. data/react_on_rails.gemspec +23 -13
  57. data/yarn.lock +3 -39
  58. metadata +75 -49
  59. data/lib/react_on_rails/server_rendering_pool/node.rb +0 -83
  60. data/lib/react_on_rails/test_helper/node_process_launcher.rb +0 -14
data/README.md CHANGED
@@ -2,89 +2,73 @@
2
2
 
3
3
  *If this projects helps you, please give us a star!*
4
4
 
5
- [ShakaCode is hiring team members](http://www.shakacode.com/about/#work-with-us) for our own app, [Friends and Guests](https://www.friendsandguests.com).
6
-
7
- # React on Rails v9 is based on Webpacker 3.0!
8
-
9
- * See the article [Introducing React on Rails v9 with Webpacker Support](https://blog.shakacode.com/introducing-react-on-rails-v9-with-webpacker-support-f2584c6c8fa4) for an overview of the integration of React on Rails with Webpacker.
10
- * [Video of running the v9 installer with Webpacker v3](https://youtu.be/M0WUM_XPaII).
11
- * See the updated [Tutorial](https://github.com/shakacode/react_on_rails/blob/master/docs/tutorial.md).
12
- * See the [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for migration instructions.
5
+ ## Need Help with Rails + Webpack + React? Want better performance?
6
+ Aloha, I'm Justin Gordon the creator and maintainer of React on Rails. I offer a [React on Rails Pro Support Plan](http://www.shakacode.com/work/shakacode-pro-support.pdf), and I can help you with:
7
+ * Optimizing your webpack setup for React on Rails.
8
+ * Upgrading from older React on Rails to newer versions.
9
+ * Better performance client and server side.
10
+ * Migrating from Angular to React.
11
+ * Best practices based on 4 years of React on Rails experience.
12
+ * Early access to the React on Rails Pro Gem and Node code, including:
13
+ * ShakaCode's Node.js rendering server for better performance for server rendering (used now at [egghead.io](https://egghead.io/)).
14
+ * Performance helpers, especially for server rendering
15
+ * Webpack configuration examples
16
+
17
+ Please [email me](mailto:justin@shakacode.com) for a free half-hour project consultation, on anything from React on Rails to any aspect of web development.
13
18
 
14
19
  ----
15
20
 
16
- Given that Webpacker already provides React integration, why would you add React on Rails? Additional features of React on Rails include:
21
+ ## React on Rails is based on Webpacker!
22
+
23
+ Given that Webpacker already provides React integration, why would you use "React on Rails"? Additional features of React on Rails include:
17
24
 
18
25
  1. Server rendering, often for SEO optimization.
19
26
  2. Easy passing of props directly from your Rails view to your React components rather than having your Rails view load and then make a separate request to your API.
20
27
  3. Redux and React-Router integration
21
28
  4. Localization support
22
29
  5. Rspec test helpers to ensure your Webpack bundles are ready for tests
30
+ 6. A supportive community
23
31
 
24
32
  ----
25
33
 
26
- ## Steps to a New App with rails/webpacker v3 plus React on Rails v9:
34
+ ## Steps to a New App with rails/webpacker v3 plus latest React on Rails:
27
35
  First be sure to run `rails -v` and check that you are using Rails 5.1.3 or above. If you are using an older version of Rails, you'll need to install webpacker with React per the instructions [here](https://github.com/rails/webpacker).
28
36
 
29
37
  ### Basic installation for a new Rails App
30
38
  *See below for steps on an existing Rails app*
31
39
 
32
40
  1. New Rails app: `rails new my-app --webpack=react`. `cd` into the directory.
33
- 2. Add gem version: `gem 'react_on_rails', '~> 9.0.1'`
34
- 3. Run the generator: `rails generate react_on_rails:install`
35
- 4. Start the app: `rails s`
36
- 5. Visit http://localhost:3000/hello_world
41
+ 2. Add gem version: `gem 'react_on_rails', '11.0.0' # Use the exact gem version to match npm version`
42
+ 3. `bundle install`
43
+ 4. Commit this to git (or else you cannot run the generator unless you pass the option --ignore-warnings).
44
+ 5. Run the generator: `rails generate react_on_rails:install`
45
+ 6. Start the app: `rails s`
46
+ 7. Visit http://localhost:3000/hello_world
37
47
 
38
48
  ### Turn on server rendering
39
49
 
40
- *The rails/wepbacker default setup does not work with hot or live reloading, yet, per [Webpacker issue #842](https://github.com/rails/webpacker/issues/842). If you want the combination of both server rendering and hot reloading during development, you will need to a custom webpack setup as shown [here](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/webpack.client.rails.hot.config.js)*
41
-
42
50
  1. Edit `app/views/hello_world/index.html.erb` and set `prerender` to `true`.
43
51
  2. Refresh the page.
44
52
 
45
53
  This is the line where you turn server rendering on by setting prerender to true:
46
54
 
47
55
  ```
48
- <%%= react_component("HelloWorld", props: @hello_world_props, prerender: false) %>
56
+ <%= react_component("HelloWorld", props: @hello_world_props, prerender: false) %>
49
57
  ```
50
58
 
51
- ---------------
52
-
53
- ## Thank you from Justin Gordon and [ShakaCode](http://www.shakacode.com)
54
-
55
- Thank you for considering using [React on Rails](https://github.com/shakacode/react_on_rails).
56
-
57
- * **Video:** [Front-End Sadness to Happiness: The React on Rails Story](https://www.youtube.com/watch?v=SGkTvKRPYrk): History, motivations, philosophy, and overview.
58
- * [Front-End Sadness to Happiness: The React on Rails Story at GORUCO 2017](https://blog.shakacode.com/front-end-sadness-to-happiness-the-react-on-rails-story-at-goruco-2017-d63b8fd26ca4)
59
-
60
- We at [ShakaCode](http://www.shakacode.com) are a small, boutique, remote-first application development company. We fund this project by:
61
-
62
- * Providing priority support and training for anything related to React + Webpack + Rails in our [Coaching Program](http://www.shakacode.com/work/shakacode-coaching-plan.pdf).
63
- * Building custom web and mobile (React Native) applications. We typically work with a technical founder or CTO and instantly provide a full development team including designers.
64
- * Migrating **Angular** + Rails to React + Rails. You can see an example of React on Rails and our work converting Angular to React on Rails at [egghead.io](https://egghead.io/browse/frameworks).
65
- * Augmenting your team to get your product completed more efficiently and quickly.
66
-
67
- My article "[Why Hire ShakaCode?](https://blog.shakacode.com/can-shakacode-help-you-4a5b1e5a8a63#.jex6tg9w9)" provides additional details about our projects.
68
-
69
- If any of this resonates with you, please email me, [justin@shakacode.com](mailto:justin@shakacode.com). I offer a free half-hour project consultation, on anything from React on Rails to any aspect of web or mobile application development for both consumer and enterprise products.
70
-
71
- We are **[currently looking to hire](http://www.shakacode.com/about/#work-with-us)** like-minded developers that wish to work on our projects, including [Friends and Guests](https://www.friendsandguests.com).
72
-
73
- I appreciate your attention and sharing of these offerings with anybody that we can help. Your support allows me to bring you and your team [front-end happiness in the Rails world](https://www.youtube.com/watch?v=SGkTvKRPYrk).
59
+ -----
74
60
 
75
- Aloha and best wishes from the ShakaCode team!
76
-
77
- ------
78
-
79
- # Community
61
+ # Community Resources
80
62
  Please [**click to subscribe**](https://app.mailerlite.com/webforms/landing/l1d9x5) to keep in touch with Justin Gordon and [ShakaCode](http://www.shakacode.com/). I intend to send announcements of new releases of React on Rails and of our latest [blog articles](https://blog.shakacode.com) and tutorials. Subscribers will also have access to **exclusive content**, including tips and examples.
81
63
 
82
64
  [![2017-01-31_14-16-56](https://cloud.githubusercontent.com/assets/1118459/22490211/f7a70418-e7bf-11e6-9bef-b3ccd715dbf8.png)](https://app.mailerlite.com/webforms/landing/l1d9x5)
83
65
 
84
66
  * **Slack Room**: [Contact us](mailto:contact@shakacode.com) for an invite to the ShakaCode Slack room! Let us know if you want to contribute.
85
67
  * **[forum.shakacode.com](https://forum.shakacode.com)**: Post your questions
86
- * **[@ShakaCode on Twitter](https://twitter.com/shakacode)**
68
+ * **[@railsonmaui on Twitter](https://twitter.com/railsonmaui)**
87
69
  * For a live, [open source](https://github.com/shakacode/react-webpack-rails-tutorial), example of this gem, see [www.reactrails.com](http://www.reactrails.com).
70
+ * See [Projects](PROJECTS.md) using and [KUDOS](./KUDOS.md) for React on Rails. Please submit yours! Please edit either page or [email us](mailto:contact@shakacode.com) and we'll add your info. We also **love stars** as it helps us attract new users and contributors.
71
+ * *See [NEWS.md](NEWS.md) for more notes over time.*
88
72
 
89
73
  ------
90
74
 
@@ -100,13 +84,14 @@ For more testimonials, see [Live Projects](PROJECTS.md) and [Kudos](./KUDOS.md).
100
84
  # Articles, Videos, and Podcasts
101
85
 
102
86
  ### Articles
103
-
104
- * [Front-End Sadness to Happiness: The React on Rails Story at GORUCO 2017](https://blog.shakacode.com/front-end-sadness-to-happiness-the-react-on-rails-story-at-goruco-2017-d63b8fd26ca4)
87
+ * [Introducing React on Rails v9 with Webpacker Support](https://blog.shakacode.com/introducing-react-on-rails-v9-with-webpacker-support-f2584c6c8fa4) for an overview of the integration of React on Rails with Webpacker.
105
88
  * [Webpacker Lite: Why Fork Webpacker?](https://blog.shakacode.com/webpacker-lite-why-fork-webpacker-f0a7707fac92)
106
89
  * [React on Rails, 2000+ 🌟 Stars](https://medium.com/shakacode/react-on-rails-2000-stars-32ff5cfacfbf#.6gmfb2gpy)
107
90
  * [The React on Rails Doctrine](https://medium.com/@railsonmaui/the-react-on-rails-doctrine-3c59a778c724)
91
+ * [Simple Tutorial](https://github.com/shakacode/react_on_rails/blob/master/docs/tutorial.md).
108
92
 
109
93
  ### Videos
94
+ * [Video of running the v9 installer with Webpacker v3](https://youtu.be/M0WUM_XPaII). History, motivations, philosophy, and overview.
110
95
  1. [GORUCO 2017: Front-End Sadness to Happiness: The React on Rails Story by Justin Gordon](https://www.youtube.com/watch?v=SGkTvKRPYrk)
111
96
  1. [egghead.io: Creating a component with React on Rails](https://egghead.io/lessons/react-creating-a-component-with-react-on-rails)
112
97
  1. [egghead.io: Creating a redux component with React on Rails](https://egghead.io/lessons/react-add-redux-state-management-to-a-react-on-rails-project)
@@ -115,44 +100,39 @@ For more testimonials, see [Live Projects](PROJECTS.md) and [Kudos](./KUDOS.md).
115
100
  1. [Basic Tutorial Walkthrough](https://youtu.be/_bjScw60FBk)
116
101
  1. [Code Walkthrough](https://youtu.be/McQ9UM-_ocQ)
117
102
 
118
- ### Podcasts
119
- * [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)
120
-
121
- ------
122
-
123
- # NEWS
124
- * 2017-09-06: **VERSION 9.0.0 shipped!** This version depends on Webpacker directly. See the [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for migration instructions.
125
- * The Docs here on `master` refer to 9.x including support for [rails/webpacker](https://github.com/rails/webpacker).
126
- *Use the [7.0.4 docs](https://github.com/shakacode/react_on_rails/tree/7.0.4) to refer to the older asset pipeline way.*
127
- * *See [NEWS.md](NEWS.md) for more notes over time.*
128
-
129
103
  ------
130
104
 
131
105
  # React on Rails
132
106
 
133
107
  **Project Objective**: To provide an opinionated and optimal framework for integrating Ruby on Rails with React via the [**Webpacker**](https://github.com/rails/webpacker) gem.
134
108
 
135
- React on Rails integrates Facebook's [React](https://github.com/facebook/react) front-end framework with Rails. React v0.14.x and greater is supported, with server rendering. [Redux](https://github.com/reactjs/redux) and [React-Router](https://github.com/reactjs/react-redux) are supported as well, also with server rendering, using **execJS**.
109
+ React on Rails integrates Facebook's [React](https://github.com/facebook/react) front-end framework with Rails. React v0.14.x and greater is supported, with server rendering. [Redux](https://github.com/reactjs/redux) and [React-Router](https://github.com/reactjs/react-router) are supported as well, also with server rendering, using **execJS**.
110
+
111
+ The ability to use a standalone Node Rendering server for better performance and tooling is supported for React on Rails Pro. Contact [justin@shakacode.com](mailto:justin@shakacode.com) for more information.
136
112
 
137
113
  ## Table of Contents
138
114
 
139
115
  + [Features](#features)
140
116
  + [Why Webpack?](#why-webpack)
141
- + [Getting Started](#getting-started)
117
+ + [rails/webpacker or custom setup for Webpack?](#webpack-configuration-custom-setup-for-webpack-or-railswebpacker)
118
+ + [Getting Started with an existing Rails app](#getting-started-with-an-existing-rails-app)
142
119
  - [Installation Overview](#installation-overview)
143
120
  - [Initializer Configuration: config/initializers/react_on_rails.rb](#initializer-configuration)
144
121
  - [Including your React Component in your Rails Views](#including-your-react-component-in-your-rails-views)
145
122
  - [I18n](#i18n)
123
+ - [Convert rails-5 API only app to rails app](#convert-rails-5-api-only-app-to-rails-app)
124
+ - [NPM](#npm)
125
+ - [Webpacker Configuration](#webpacker-configuration)
146
126
  + [How it Works](#how-it-works)
147
127
  - [Client-Side Rendering vs. Server-Side Rendering](#client-side-rendering-vs-server-side-rendering)
148
128
  - [Building the Bundles](#building-the-bundles)
149
- - [Rails Context](#rails-context)
129
+ - [Rails Context and Generator Functions](#rails-context-and-generator-functions)
150
130
  - [Globally Exposing Your React Components](#globally-exposing-your-react-components)
151
131
  - [ReactOnRails View Helpers API](#reactonrails-view-helpers-api)
152
132
  - [ReactOnRails JavaScript API](#reactonrails-javascript-api)
153
133
  - [React-Router](#react-router)
154
134
  - [Deployment](#deployment)
155
- + [Integration with Node.js for Server Rendering](#user-content-integration-with-nodejs-for-server-rendering)
135
+ + [Integration with Node.js for Server Rendering](#integration-with-nodejs-for-server-rendering)
156
136
  + [Additional Documentation](#additional-documentation)
157
137
  + [Contributing](#contributing)
158
138
  + [License](#license)
@@ -179,18 +159,48 @@ This usage of webpack fits neatly and simply into existing Rails apps. You can i
179
159
  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 [
180
160
  Universal React with Rails: Part I](https://medium.com/@alexfedoseev/isomorphic-react-with-rails-part-i-440754e82a59).
181
161
 
182
- ## Upgrade
162
+ ## Webpack Configuration: custom setup for Webpack or rails/webpacker?
163
+
164
+ Version 9 of React on Rails added support for the rails/webpacker view helpers so that Webpack produced assets would no longer pass through the Rails asset pipeline. As part of this change, React on Rails added a configuration option to support customization of the node_modules directory. This allowed React on Rails to support the rails/webpacker configuration of the Webpack configuration.
165
+
166
+ A key decision in your use React on Rails is whether you go with the rails/webpacker default setup or the traditional React on Rails setup of putting all your client side files under the `/client` directory. While there are technically 2 independent choices involved, the directory structure and the mechanism of Webpack configuration, for simplicity sake we'll assume that these choices go together.
167
+
168
+ ### Traditional React on Rails using the /client directory
169
+
170
+ Until version 9, all React on Rails apps used the `/client` directory for configuring React on Rails in terms of the configuration of Webpack and location of your JavaScript and Webpack files, including the node_modules directory. Version 9 changed the default to `/` for the `node_modules` location using this value in `config/initializers/react_on_rails.rb`: `config.node_modules_location`.
171
+
172
+ The [ShakaCode Team](http://www.shakacode.com) _recommends_ this approach for projects beyond the simplest cases as it provides the greatest transparency in your webpack and overall client-side setup. The *big advantage* to this is that almost everything within the `/client` directory will apply if you wish to convert your client-side code to a pure Single Page Application that runs without Rails. This allows you to google for how to do something with Webpack configuration and what applies to a non-Rails app will apply just as well to a React on Rails app.
173
+
174
+ The two best examples of this patten are the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and the integration test example in [spec/dummy](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy).
175
+
176
+ In this case, you don't need to understand the nuances of customization of your Wepback config via the [Webpacker mechanism](https://github.com/rails/webpacker/blob/master/docs/webpack.md).
177
+
178
+
179
+ ### rails/webpacker Setup
180
+
181
+ Typical rails/webpacker apps have a standard directory structure as documented [here](https://github.com/rails/webpacker/blob/master/docs/folder-structure.md). If you follow the steps in the the [basic tutorial](https://github.com/shakacode/react_on_rails/blob/master/docs/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, you need to consult with the [rails/webpacker Webpack configuration](https://github.com/rails/webpacker/blob/master/docs/webpack.md).
182
+
183
+ Version 9 made this the default for generated apps for 2 reasons:
184
+
185
+ 1. It's less code to generate and thus less to explain.
186
+ 2. `rails/webpacker` might be viewed as a convention in the Rails community.
187
+
188
+ The *advantage* of this is that there is very little code needed to get started and you don't need to understand really anything about Webpack customization. The *big disadvantage* to this is that you will need to learn the ins and outs of the [rails/webpacker way to customize Webpack](https://github.com/rails/webpacker/blob/master/docs/webpack.md) which differs from the plain [Webpack way](https://webpack.js.org/).
189
+
190
+ Overall, consider carefully if you prefer the `rails/webpacker` directory structure and Webpack configuration, over the placement of all client side files within the `/client` directory along with conventional Webpack configuration.
191
+
192
+ See [Issue 982: Tutorial Generating Correct Project Structure?](https://github.com/shakacode/react_on_rails/issues/982) to discuss this issue.
183
193
 
184
- To upgrade existing apps to React on Rails 8 see the [Installation Overview](docs/basics/installation-overview.md)
185
194
 
186
195
  ## Getting Started with an existing Rails app
187
196
 
188
197
  **For more detailed instructions on a fresh Rails app**, see the [React on Rails Basic Tutorial](docs/tutorial.md).
189
198
 
199
+ **If you have rails-5 API only project**, first [convert the rails-5 API only app to rails app](#convert-rails-5-api-only-app-to-rails-app) before [getting started](#getting-started-with-an-existing-rails-app).
190
200
  1. Add the following to your Gemfile and `bundle install`. We recommend fixing the version of React on Rails, as you will need to keep the exact version in sync with the version in your `client/package.json` file.
191
201
 
192
202
  ```ruby
193
- gem "react_on_rails", "9.0.0"
203
+ gem "react_on_rails", "11.0.0"
194
204
  gem "webpacker", "~> 3.0"
195
205
  ```
196
206
 
@@ -231,7 +241,7 @@ See the [Installation Overview](docs/basics/installation-overview.md) for a conc
231
241
 
232
242
  ### Initializer Configuration
233
243
 
234
- Configure the `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [spec/dummy/config/initializers/react_on_rails.rb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/initializers/react_on_rails.rb) for a detailed example of configuration, including comments on the different values to configure.
244
+ Configure the file `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](https://github.com/shakacode/react_on_rails/tree/master/docs/basics/configuration.md) for documentation of all configuration options.
235
245
 
236
246
  ### Including your React Component in your Rails Views
237
247
 
@@ -276,20 +286,40 @@ React on Rails provides an option for automatic conversions of Rails `*.yml` loc
276
286
 
277
287
  See the [How to add I18n](docs/basics/i18n.md) for a summary of adding I18n.
278
288
 
279
- ## NPM
289
+ ### Convert rails-5 API only app to rails app
290
+
291
+ 1. Go to the directory where you created your app
292
+
293
+ ```
294
+ rails new your-current-app-name
295
+ ```
296
+
297
+ Rails will start creating the app and will skip the files you have already created. If there is some conflict then it will stop and you need to resolve it manually. be careful at this step as it might replace you current code in conflicted files.
298
+
299
+ 2. Resolve conflicts
300
+
301
+ ```
302
+ 1. Press "d" to see the difference
303
+ 2. If it is only adding lines then press "y" to continue
304
+ 3. If it is removeing some of your code then press "n" and add all additions manually
305
+ ```
306
+
307
+ 3. Run `bundle install` and follow [Getting started](#getting-started-with-an-existing-rails-app)
308
+
309
+
310
+ ### NPM
280
311
  All JavaScript in React On Rails is loaded from npm: [react-on-rails](https://www.npmjs.com/package/react-on-rails). To manually install this (you did not use the generator), assuming you have a standard configuration, run this command (assuming you are in the directory where you have your `node_modules`):
281
312
 
282
313
  ```bash
283
- yarn add react-on-rails
314
+ yarn add react-on-rails --exact
284
315
  ```
285
316
 
286
- That will install the latest version and update your package.json.
317
+ That will install the latest version and update your package.json. **NOTE:** the `--exact` flag will ensure that you do not have a "~" or "^" for your react-on-rails version in your package.json.
287
318
 
288
- ## Webpacker Configuration
319
+ ### Webpacker Configuration
289
320
 
290
321
  React on Rails users should set configuration value `compile` to false, as React on Rails handles compilation for test and production environments.
291
322
 
292
-
293
323
  ## How it Works
294
324
  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/webpack`, which are then loaded by sprockets. These generated bundle files have been added to your `.gitignore` for your convenience.
295
325
 
@@ -300,21 +330,18 @@ In most cases, you should use the `prerender: false` (default behavior) with the
300
330
 
301
331
  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 [mini_racer](https://github.com/discourse/mini_racer) as ExecJS's runtime. The generator will automatically add it to your Gemfile for you (once we complete [#501](https://github.com/shakacode/react_on_rails/issues/501)).
302
332
 
303
- In the following screenshot you can see the 3 parts of React on Rails rendering:
333
+ If you open the HTML source of any web page using React on Rails, you'll see the 3 parts of React on Rails rendering:
304
334
 
305
- 1. A hidden HTML div contains the properties of the React component, such as the registered name and any props. A JavaScript function runs after the page loads to take this data and build initialize React components.
306
- 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
335
+ 1. A script tag containing the properties of the React component, such as the registered name and any props. A JavaScript function runs after the page loads, using this data to build and initialize your React components.
336
+ 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.
307
337
  3. Additional JavaScript is placed to console-log any messages, such as server rendering errors. Note: these server side logs can be configured only to be sent to the server logs.
308
338
 
309
339
  **Note**:
310
340
 
311
341
  * 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.
312
- * 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 `<script>` tag.
313
-
314
- ![Comparison of a normal React Component with its server-rendered version](https://cloud.githubusercontent.com/assets/1118459/12607542/a959d5c8-c48a-11e5-8187-2433d543ccaa.png)
315
342
 
316
343
  ### Building the Bundles
317
- Each time you change your client code, you will need to re-generate the bundles (the webpack-created JavaScript files included in application.js). The included Foreman `Procfile.dev` will take care of this for you by watching your JavaScript code files for changes. Simply run `foreman start -f Procfile.dev`.
344
+ Each time you change your client code, you will need to re-generate the bundles (the webpack-created JavaScript files included in application.js). The included Foreman `Procfile.dev` will take care of this for you by starting a webpack process with the watch flag. This will watch your JavaScript code files for changes. Simply run `foreman start -f Procfile.dev`.
318
345
 
319
346
  On production deployments that use asset precompilation, such as Heroku deployments, React on Rails, by default, will automatically run webpack to build your JavaScript bundles. You can see the source code for what gets added to your precompilation [here](https://github.com/shakacode/react_on_rails/tree/master/lib/tasks/assets.rake). For more information on this topic, see [the doc on Heroku deployment](./docs/additional-reading/heroku-deployment.md#more-details-on-precompilation-using-webpack-to-create-javascript-assets).
320
347
 
@@ -322,21 +349,19 @@ If you have used the provided generator, these bundles will automatically be add
322
349
 
323
350
 
324
351
  ### Generator Functions
325
- Why would you create a function that returns a React component rather than simply an Object that is a React class?
352
+ You have 2 ways to specify your React components. You can either register the React component directly, or you can create a function that returns a React component. Creating a function has the following benefits:
326
353
 
327
- 1. You need access to the `railsContext`. See documentation for the railsContext in terms of why you might need it. You **need** a generator function to access the `railsContext`.
328
- 1. You may want the ability to use the passed-in props to initialize a redux store or set up react-router
329
- 1. You may want to return different components depending on what's in the props.
354
+ 1. You have access to the `railsContext`. See documentation for the railsContext in terms of why you might need it. You **need** a generator function to access the `railsContext`.
355
+ 1. You can use the passed-in props to initialize a redux store or set up react-router.
356
+ 1. You can return different components depending on what's in the props.
330
357
 
331
358
  ReactOnRails will automatically detect a registered generator function. Thus, there is no difference between registering a React Component versus a "generator function."
332
359
 
333
- 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 }.
360
+ 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 }. Make sure you use this function with `react_component_hash`.
334
361
 
335
362
  For server rendering, if you wish to return multiple HTML strings from a generator function, you may return an Object from your generator function with a single top level property of `renderedHtml`. Inside this Object, place a key called `componentHtml`, along with any other needed keys. An example scenario of this is when you are using side effects libraries like [React Helmet](https://github.com/nfl/react-helmet). Your Ruby code will get this Object as a Hash containing keys componentHtml and any other custom keys that you added:
336
363
  { renderedHtml: { componentHtml, customKey1, customKey2} }
337
364
 
338
- Note: The functionality in the above paragraph requires the use of our new `react_component_hash` method. Said functionality in our `react_component` method is now deprecated.
339
-
340
365
  ### Rails Context and Generator Functions
341
366
  When you use a "generator function" to create react components (or renderedHtml on the server), or you used shared redux stores, you get two params passed to your function that creates a React component:
342
367
 
@@ -383,6 +408,7 @@ The `railsContext` has: (see implementation in file [react_on_rails_helper.rb](h
383
408
 
384
409
  ```ruby
385
410
  {
411
+ railsEnv: Rails.env
386
412
  # URL settings
387
413
  href: request.original_url,
388
414
  location: "#{uri.path}#{uri.query.present? ? "?#{uri.query}": ""}",
@@ -420,6 +446,9 @@ Consider this line in depth:
420
446
  The outer `{...` is for the [JSX spread operator for attributes](https://facebook.github.io/react/docs/jsx-in-depth.html#spread-attributes) and the innner `{...` is for the [Spread in object literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Spread_in_object_literals).
421
447
 
422
448
  #### Use Cases
449
+ ##### Heroku Preboot Considerations
450
+ [Heroku Preboot](https://devcenter.heroku.com/articles/preboot) is a feature on Heroku that allows for faster deploy times. When you promote your staging app to production, Preboot simply switches the production server to point at the staging app's container. This means it can deploy much faster since it doesn't have to rebuild anything. However, this means that if you use the [Define Plugin](https://github.com/webpack/docs/wiki/list-of-plugins#defineplugin) to provide the rails environment to your client code as a variable, that variable will erroneously still have a value of `Staging` instead of `Production`. The `Rails.env` provided at runtime in the railsContext is, however, accurate.
451
+
423
452
  ##### Needing the current URL path for server rendering
424
453
  Suppose you want to display a nav bar with the current navigation link highlighted by the URL. When you server-render the code, your code will need to know the current URL/path. The new `railsContext` has this information. Your application will apply something like an "active" class on the server rendering.
425
454
 
@@ -469,7 +498,7 @@ This is how to expose a component to the `react_component` view helper.
469
498
 
470
499
  #### Different Server-Side Rendering Code (and a Server Specific Bundle)
471
500
 
472
- You may want different initialization for your server-rendered components. For example, if you have an 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!
501
+ You may want different initialization for your server-rendered components. For example, if you have an 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. Note, check if `window` is defined has a similar effect.
473
502
 
474
503
  If you want different code to run, you'd set up 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.
475
504
 
@@ -618,13 +647,16 @@ If you are using [jquery-ujs](https://github.com/rails/jquery-ujs) for AJAX call
618
647
  [React Router](https://github.com/reactjs/react-router) is supported, including server-side rendering! See:
619
648
 
620
649
  1. [React on Rails docs for react-router](./docs/additional-reading/react-router.md)
621
- 1. Examples in [spec/dummy/app/views/react_router](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/views/react_router) and follow to the JavaScript code in the [spec/dummy/client/app/startup/ServerRouterApp.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/startup/ServerRouterApp.jsx).
650
+ 1. Examples in [spec/dummy/app/views/react_router](./spec/dummy/app/views/react_router) and follow to the JavaScript code in the [spec/dummy/client/app/startup/ServerRouterApp.jsx](spec/dummy/client/app/startup/ServerRouterApp.jsx).
622
651
  1. [Code Splitting docs](./docs/additional-reading/code-splitting.md) for information about how to set up code splitting for server rendered routes.
623
652
 
653
+ ## Caching and Performance
654
+ Consider fragment and http caching of pages that contain React on Rails components. See [Caching and Performance](./docs/additional-reading/caching-and-performance.md) for more details.
655
+
624
656
  ## Deployment
625
- * Version 6.0 puts the necessary precompile steps automatically in the rake precompile step. You can, however, disable this by setting certain values to nil in the [config/initializers/react_on_rails.rb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/initializers/react_on_rails.rb).
626
- * `config.symlink_non_digested_assets_regex`: Set to nil to turn off the setup of non-js assets.
657
+ * React on Rails puts the necessary precompile steps automatically in the rake precompile step. You can, however, disable this by setting certain values to nil in the [config/initializers/react_on_rails.rb](./docs/additional-reading/rspec_configuration.md).
627
658
  * `build_production_command`: Set to nil to turn off the precompilation of the js assets.
659
+ * `config.symlink_non_digested_assets_regex`: Default is nil, turning off the setup of non-js assets. This should be nil except when when using Sprockets rather than Webpacker.
628
660
  * See the [Heroku Deployment](./docs/additional-reading/heroku-deployment.md) doc for specifics regarding Heroku. The information here should apply to other deployments.
629
661
 
630
662
  ## Integration with Node.js for Server Rendering
@@ -632,7 +664,7 @@ If you are using [jquery-ujs](https://github.com/rails/jquery-ujs) for AJAX call
632
664
  If you want to use a node server for server rendering, [get in touch](mailto:justin@shakacode.com). ShakaCode has built a premium Node rendering server for React on Rails.
633
665
 
634
666
  ## Additional Documentation
635
- **Try out our new [Documentation Gitbook](https://shakacode.gitbooks.io/react-on-rails/content/) for improved readability & reference!**
667
+ **Try out our [Documentation Gitbook](https://shakacode.gitbooks.io/react-on-rails/content/) for improved readability & reference.**
636
668
 
637
669
  + **Rails**
638
670
  + [Rails Assets](./docs/additional-reading/rails-assets.md)
@@ -666,18 +698,15 @@ If you want to use a node server for server rendering, [get in touch](mailto:jus
666
698
  + [Hot Reloading of Assets For Rails Development](./docs/additional-reading/hot-reloading-rails-development.md)
667
699
  + [Heroku Deployment](./docs/additional-reading/heroku-deployment.md)
668
700
  + [Updating Dependencies](./docs/additional-reading/updating-dependencies.md)
701
+ + [Caching and Performance](./docs/additional-reading/caching-and-performance.md)
669
702
 
670
703
  + **API**
671
704
  + [JavaScript API](./docs/api/javascript-api.md)
672
705
  + [Ruby API](./docs/api/ruby-api.md)
673
706
  + [Setting up Hot Reloading during Rails Development, API docs](./docs/api/ruby-api-hot-reload-view-helpers.md)
674
707
 
675
- + **[CONTRIBUTING](CONTRIBUTING.md)**
676
- + [Generator Testing](./docs/contributor-info/generator-testing.md)
677
- + [Linting](./docs/contributor-info/linters.md)
678
- + [Releasing](./docs/contributor-info/releasing.md)
679
-
680
708
  + **Misc**
709
+ + [Upgrading](./docs/basics/upgrading-react-on-rails.md)
681
710
  + [Tips](./docs/additional-reading/tips.md)
682
711
  + [Changelog](./CHANGELOG.md)
683
712
  + [Projects](./PROJECTS.md)
@@ -686,6 +715,10 @@ If you want to use a node server for server rendering, [get in touch](mailto:jus
686
715
  + [Code of Conduct](./docs/misc/code_of_conduct.md)
687
716
  + [The React on Rails Doctrine](https://medium.com/@railsonmaui/the-react-on-rails-doctrine-3c59a778c724)
688
717
  + [React on Rails, 2000+ 🌟 Stars](https://medium.com/shakacode/react-on-rails-2000-stars-32ff5cfacfbf#.6gmfb2gpy)
718
+ + [Generator Testing](./docs/contributor-info/generator-testing.md)
719
+ + [Linting](./docs/contributor-info/linters.md)
720
+ + [Releasing](./docs/contributor-info/releasing.md)
721
+ + **[CONTRIBUTING](CONTRIBUTING.md)**
689
722
 
690
723
  ## Demos
691
724
  + [www.reactrails.com](http://www.reactrails.com) with the source at [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/).
@@ -698,14 +731,13 @@ If you want to use a node server for server rendering, [get in touch](mailto:jus
698
731
 
699
732
  ## Dependencies
700
733
  + Ruby 2.1 or greater
701
- + Rails 4.2 or greater
702
- + Rails 3.2 will work and is tested up to 6.8.x. We are not testing it for new releases. If you find an issue, you will have to submit a PR to get it fixed.
734
+ + Rails 3.2 or greater
703
735
  + Node 5.5 or greater
704
736
 
705
737
  ## Contributing
706
- 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 Code of Conduct](docs/misc/code_of_conduct.md)).
738
+ Bug reports and pull requests are welcome. This project is intended to be a welcoming space for collaboration, and contributors are expected to adhere to our version of the [Contributor Covenant Code of Conduct](docs/misc/code_of_conduct.md)).
707
739
 
708
- See [Contributing](CONTRIBUTING.md) to get started.
740
+ See [Contributing](CONTRIBUTING.md) to get started. See [contribution help wanted](https://github.com/shakacode/react_on_rails/labels/contributions%3A%20up%20for%20grabs%21).
709
741
 
710
742
  ## License
711
743
  The gem is available as open source under the terms of the [MIT License](./docs/LICENSE.md).
@@ -713,11 +745,11 @@ The gem is available as open source under the terms of the [MIT License](./docs/
713
745
  ## Authors
714
746
  [The Shaka Code team!](http://www.shakacode.com/about/)
715
747
 
716
- The origins of the project began with the need to do a rich JavaScript interface for ShakaCode's client [Madrone](http://madroneco.com/) and the choice to use Webpack and Rails, as described in [Fast Rich Client Rails Development With Webpack and the ES6 Transpiler](http://www.railsonmaui.com/blog/2014/10/03/integrating-webpack-and-the-es6-transpiler-into-an-existing-rails-project/).
748
+ The origins of the project began with the need to do a rich JavaScript interface for a ShakaCode's client. The choice to use Webpack and Rails is described in [Fast Rich Client Rails Development With Webpack and the ES6 Transpiler](http://www.railsonmaui.com/blog/2014/10/03/integrating-webpack-and-the-es6-transpiler-into-an-existing-rails-project/).
717
749
 
718
750
  The gem project started with [Justin Gordon](https://github.com/justin808/) pairing with [Samnang Chhun](https://github.com/samnang) to figure out how to do server rendering with Webpack plus Rails. [Alex Fedoseev](https://github.com/alexfedoseev) then joined in. [Rob Wise](https://github.com/robwise), [Aaron Van Bokhoven](https://github.com/aaronvb), and [Andy Wang](https://github.com/yorzi) did the bulk of the generators. Many others have [contributed](https://github.com/shakacode/react_on_rails/graphs/contributors).
719
751
 
720
- We owe much gratitude to the work of the [react-rails gem](https://github.com/reactjs/react-rails).
752
+ The gem was initially inspired by the [react-rails gem](https://github.com/reactjs/react-rails).
721
753
 
722
754
  # Thanks!
723
755
  The following companies support open source, and ShakaCode uses their products!
@@ -727,27 +759,15 @@ The following companies support open source, and ShakaCode uses their products!
727
759
 
728
760
  *If you'd like to support React on Rails and have your company listed here, [get in touch](mailto:justin@shakacode.com).*
729
761
 
730
- # FINAL NOTES
731
- * See [Projects](PROJECTS.md) using and [KUDOS](./KUDOS.md) for React on Rails. Please submit yours! Please edit either page or [email us](mailto:contact@shakacode.com) and we'll add your info. We also **love stars** as it helps us attract new users and contributors.
732
- * Follow [@railsonmaui](https://twitter.com/railsonmaui) and [@shakacode](https://twitter.com/shakacode) on Twitter for updates on releases. We've also got a forum category dedicated to [react_on_rails](https://forum.shakacode.com/c/rails/reactonrails).
733
- * Please [Subscribe](https://app.mailerlite.com/webforms/landing/l1d9x5) to keep in touch with Justin Gordon and [ShakaCode](http://www.shakacode.com/). I intend to send announcements of new releases of React on Rails and of our latest [blog articles](https://blog.shakacode.com) and tutorials. Subscribers will also have access to **exclusive content**, including tips and examples.
734
-
735
- [![2017-01-31_14-16-56](https://cloud.githubusercontent.com/assets/1118459/22490211/f7a70418-e7bf-11e6-9bef-b3ccd715dbf8.png)](https://app.mailerlite.com/webforms/landing/l1d9x5)
736
-
737
762
  ---
738
763
 
739
- *Identical to top of page*
740
-
741
764
  ## Thank you from Justin Gordon and [ShakaCode](http://www.shakacode.com)
742
765
 
743
766
  Thank you for considering using [React on Rails](https://github.com/shakacode/react_on_rails).
744
767
 
745
- * **Video:** [Front-End Sadness to Happiness: The React on Rails Story](https://www.youtube.com/watch?v=SGkTvKRPYrk): History, motivations, philosophy, and overview.
746
- * *[Click here for talk slides](http://www.shakacode.com/talks).*
747
-
748
768
  We at [ShakaCode](http://www.shakacode.com) are a small, boutique, remote-first application development company. We fund this project by:
749
769
 
750
- * Providing priority support and training for anything related to React + Webpack + Rails in our [Coaching Program](http://www.shakacode.com/work/shakacode-coaching-plan.pdf).
770
+ * Providing priority support and training for anything related to React + Webpack + Rails in our [Pro Support program](http://www.shakacode.com/work/shakacode-pro-support.pdf).
751
771
  * Building custom web and mobile (React Native) applications. We typically work with a technical founder or CTO and instantly provide a full development team including designers.
752
772
  * Migrating **Angular** + Rails to React + Rails. You can see an example of React on Rails and our work converting Angular to React on Rails at [egghead.io](https://egghead.io/browse/frameworks).
753
773
  * Augmenting your team to get your product completed more efficiently and quickly.
@@ -756,10 +776,6 @@ My article "[Why Hire ShakaCode?](https://blog.shakacode.com/can-shakacode-help-
756
776
 
757
777
  If any of this resonates with you, please email me, [justin@shakacode.com](mailto:justin@shakacode.com). I offer a free half-hour project consultation, on anything from React on Rails to any aspect of web or mobile application development for both consumer and enterprise products.
758
778
 
759
- We are **[currently looking to hire](http://www.shakacode.com/about/#work-with-us)** like-minded developers that wish to work on our projects, including [Friends and Guests](https://www.friendsandguests.com).
760
-
761
- I appreciate your attention and sharing of these offerings with anybody that we can help. Your support allows me to bring you and your team [front-end happiness in the Rails world](https://www.youtube.com/watch?v=SGkTvKRPYrk).
779
+ We are **[currently looking to hire](http://www.shakacode.com/about/#work-with-us)** like-minded developers that wish to work on our projects, including [Hawaii Chee](https://www.hawaiichee.com).
762
780
 
763
- Aloha and best wishes from the ShakaCode team!
764
-
765
- ------
781
+ Aloha and best wishes from Justin and the ShakaCode team!