react_on_rails 12.0.0.pre.beta.4 → 12.0.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (41) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/lint-js-and-ruby.yml +53 -0
  3. data/.github/workflows/main.yml +178 -0
  4. data/.github/workflows/package-js-tests.yml +35 -0
  5. data/.github/workflows/rspec-package-specs.yml +45 -0
  6. data/.rubocop.yml +1 -0
  7. data/.travis.yml +8 -4
  8. data/CHANGELOG.md +37 -20
  9. data/CONTRIBUTING.md +1 -1
  10. data/NEWS.md +5 -0
  11. data/README.md +65 -62
  12. data/SUMMARY.md +1 -1
  13. data/docs/additional-reading/converting-from-custom-webpack-config-to-rails-webpacker-config.md +10 -0
  14. data/docs/additional-reading/react-router.md +1 -1
  15. data/docs/additional-reading/recommended-project-structure.md +69 -0
  16. data/docs/additional-reading/server-rendering-tips.md +4 -1
  17. data/docs/api/javascript-api.md +3 -3
  18. data/docs/api/redux-store-api.md +2 -2
  19. data/docs/api/view-helpers-api.md +4 -4
  20. data/docs/basics/client-vs-server-rendering.md +2 -0
  21. data/docs/basics/configuration.md +1 -1
  22. data/docs/basics/hmr-and-hot-reloading-with-the-webpack-dev-server.md +64 -9
  23. data/docs/basics/react-server-rendering.md +8 -5
  24. data/docs/basics/render-functions-and-railscontext.md +1 -1
  25. data/docs/basics/upgrading-react-on-rails.md +47 -10
  26. data/docs/basics/webpack-configuration.md +12 -18
  27. data/docs/misc/doctrine.md +0 -1
  28. data/docs/outdated/code-splitting.md +3 -3
  29. data/docs/tutorial.md +6 -0
  30. data/lib/generators/react_on_rails/templates/dev_tests/spec/rails_helper.rb +4 -1
  31. data/lib/react_on_rails/helper.rb +8 -8
  32. data/lib/react_on_rails/utils.rb +5 -1
  33. data/lib/react_on_rails/version.rb +1 -1
  34. data/lib/react_on_rails/webpacker_utils.rb +4 -4
  35. data/lib/tasks/assets.rake +17 -5
  36. data/package.json +1 -1
  37. data/rakelib/examples.rake +1 -1
  38. data/rakelib/lint.rake +1 -1
  39. data/rakelib/release.rake +1 -3
  40. metadata +10 -5
  41. data/docs/basics/recommended-project-structure.md +0 -77
@@ -62,7 +62,7 @@ cd react_on_rails/
62
62
  yarn
63
63
 
64
64
  # Update the lib directory with babel compiled files
65
- yarn run build:watch
65
+ yarn run build-watch
66
66
  ```
67
67
 
68
68
  You need to do this once:
data/NEWS.md CHANGED
@@ -2,6 +2,11 @@
2
2
 
3
3
  *We'll keep a history of the news. A few bullets at the top will also show on the [README.md](./README.md).*
4
4
 
5
+ * July 8, 2020: Release **v12**.
6
+ 1. **React Hooks Support** for top level components
7
+ 2. **Typescript bindings**
8
+ 3. **rails/webpacker** "just works" with React on Rails by default.
9
+ 4. i18n support for generating a JSON file rather than a JS file.
5
10
  * 2018-02-27: **Version 10.1.2** Supports the React API for ReactDOM.hydrate.
6
11
  * 2017-09-06: **VERSION 9.0.0 shipped!** This version depends on Webpacker directly. See [Upgrading React on Rails](./docs/basics/upgrading-react-on-rails.md) for more concise instructions on upgrading.
7
12
  * Always see the [CHANGELOG.md](./CHANGELOG.md) for the latest project changes.
data/README.md CHANGED
@@ -11,35 +11,39 @@
11
11
 
12
12
  [![License](https://img.shields.io/badge/license-mit-green.svg)](./LICENSE.md) [![Build Status](https://travis-ci.org/shakacode/react_on_rails.svg?branch=master)](https://travis-ci.org/shakacode/react_on_rails) [![Gem Version](https://badge.fury.io/rb/react_on_rails.svg)](https://badge.fury.io/rb/react_on_rails) [![npm version](https://badge.fury.io/js/react-on-rails.svg)](https://badge.fury.io/js/react-on-rails) [![Code Climate](https://codeclimate.com/github/shakacode/react_on_rails/badges/gpa.svg)](https://codeclimate.com/github/shakacode/react_on_rails) [![Coverage Status](https://coveralls.io/repos/shakacode/react_on_rails/badge.svg?branch=master&service=github)](https://coveralls.io/github/shakacode/react_on_rails?branch=master) [![](https://ruby-gem-downloads-badge.herokuapp.com/react_on_rails?type=total)](https://rubygems.org/gems/react_on_rails)
13
13
 
14
- *These are the docs for React on Rails 12, coming soon. To see the version 11 docs, [click here](https://github.com/shakacode/react_on_rails/tree/11.3.0).*
14
+ *These are the docs for React on Rails 12. To see the version 11 docs, [click here](https://github.com/shakacode/react_on_rails/tree/11.3.0).*
15
15
 
16
16
  #### News
17
- **June 24, 2020**:
18
- 1. Gem version: 12.0.0.pre.beta.3 and npm version 12.0.0-beta.3 released! Please try this out!
19
- Major enhancements:
20
- 1. Proper support for React Hooks
21
- 2. Typescript bindings
22
- 3. i18n support for generating a JSON file rather than a JS file.
23
- 4. Tighter rails/webpacker integration
17
+ **August 2, 2020**: See the example repo of [React on Rails Tutorial With SSR, HMR fast refresh, and TypeScript](https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh) for a new way to setup the creation of your SSR bundle with `rails/webpacker`.
18
+
19
+ **July 8, 2020**: Release v12 of React on Rails.
20
+
21
+ **Major Improvements**
22
+
23
+ 1. **React Hooks Support** for top level components
24
+ 2. **Typescript bindings**
25
+ 3. **rails/webpacker** "just works" with React on Rails by default.
26
+ 4. i18n support for generating a JSON file rather than a JS file.
24
27
 
25
- Be sure to see the [CHANGELOG.md](./CHANGELOG.md) and read the upgrade instructions:
26
- [docs/basics/upgrading-react-on-rails](./docs/basics/upgrading-react-on-rails.md#upgrading-to-v12).
28
+ Be sure to see the [CHANGELOG.md](./CHANGELOG.md) and read the upgrade instructions:
29
+ [docs/basics/upgrading-react-on-rails](./docs/basics/upgrading-react-on-rails.md#upgrading-to-v12).
27
30
 
28
- 2. See Justin's RailsConf talk: [Webpacker, It-Just-Works, But How?](http://railsconf.com/2020/video/justin-gordon-webpacker-it-just-works-but-how).
29
-
30
- **April 2, 2020**:
31
+ * See Justin's RailsConf talk: [Webpacker, It-Just-Works, But How?](http://railsconf.com/2020/video/justin-gordon-webpacker-it-just-works-but-how).
31
32
  * Are you interested in support for React on Rails? If so check out [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro).
32
33
  * HMR is working with [Loadable Components](https://loadable-components.com) for a both amazing hot-reloading developer experience and great runtime performance. Please [email me](mailto:justin@shakacode.com) if you'd like to use [Loadable Components Code Splitting](https://loadable-components.com/docs/code-splitting/) to speed up your app by reducing your bundle sizes and lazily loading the code that's needed.
33
- * `react_on_rails` fully supports `rails/webpacker`. The example test app in `spec/dummy` was recently converted over to use rails/webpacker v4. It's a good example of how to leverage rails/webpacker's webpack configuration.
34
+ * `react_on_rails` fully supports `rails/webpacker`. The example test app in `spec/dummy` was recently converted over to use rails/webpacker v4+. It's a good example of how to leverage rails/webpacker's webpack configuration.
34
35
 
35
36
  ---
36
37
 
37
38
  #### About
38
39
  React on Rails integrates Rails with (server rendering of) Facebook's [React](https://github.com/facebook/react) front-end framework.
39
40
 
40
- This project is sponsored by the software consulting firm [ShakaCode](https://www.shakacode.com). We focus on React front-ends, often with Ruby on Rails or Gatsby. The best way to see what we do is to see the details of [our recent work](https://www.shakacode.com/recent-work).
41
+ This project is maintained by the software consulting firm [ShakaCode](https://www.shakacode.com). We focus on Ruby on Rails applications with React front-ends, often using TypeScript or ReasonML. We also build Gatsby sites. See [our recent work](https://www.shakacode.com/recent-work) for examples of what we do.
41
42
 
42
- Interested in optimizing your webpack setup for React on Rails including code splitting with react-router v4, webpack v4, and react-loadable with server side rendering? We just did this for Popmenu, [lowering Heroku costs 20-25% while getting a 73% decrease in average response times](https://www.shakacode.com/recent-work/popmenu/).
43
+ Interested in optimizing your webpack setup for React on Rails including code
44
+ splitting with [react-router](https://github.com/ReactTraining/react-router#readme),
45
+ and [loadable-components](https://loadable-components.com/) with server-side rendering?
46
+ We just did this for Popmenu, [lowering Heroku costs 20-25% while getting a 73% decrease in average response times](https://www.shakacode.com/recent-work/popmenu/).
43
47
 
44
48
  Feel free to contact Justin Gordon, [justin@shakacode.com](mailto:justin@shakacode.com), maintainer of React on Rails, for more information.
45
49
 
@@ -49,16 +53,16 @@ Feel free to contact Justin Gordon, [justin@shakacode.com](mailto:justin@shakaco
49
53
 
50
54
  ## Project Objective
51
55
 
52
- To provide a high performance framework for integrating Ruby on Rails with React via the [**Webpacker**](https://github.com/rails/webpacker) gem especially in regards to React Server Rendering.
56
+ To provide a high performance framework for integrating Ruby on Rails with React via the [**Webpacker**](https://github.com/rails/webpacker) gem especially in regards to React Server-Side Rendering for better SEO and improved performance.
53
57
 
54
58
  ## Features and Why React on Rails?
55
59
 
56
- Given that rails/webpacker gem already provides basic React integration, why would you use "React on Rails"?
60
+ Given that `rails/webpacker` gem already provides basic React integration, why would you use "React on Rails"?
57
61
 
58
- 1. The 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.
62
+ 1. 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.
59
63
  1. Tight integration with [rails/webpacker](https://github.com/rails/webpacker).
60
- 1. Server rendering, often used for SEO crawler indexing and UX performance, is not offered by rails/webpacker.
61
- 1. [Redux](https://github.com/reactjs/redux) and [React Router](https://github.com/reactjs/react-router) integration with server-side-rendering.
64
+ 1. Server-Side Rendering (SSR), often used for SEO crawler indexing and UX performance, is not offered by `rails/webpacker`.
65
+ 1. [Redux](https://github.com/reactjs/redux) and [React Router](https://github.com/ReactTraining/react-router#readme) integration with server-side-rendering.
62
66
  1. [Internationalization (I18n) and (localization)](https://github.com/shakacode/react_on_rails/blob/master/docs/basics/i18n.md)
63
67
  1. A supportive community. This [web search shows how live public sites are using React on Rails](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com/).
64
68
  1. [Reason ML Support](https://github.com/shakacode/reason-react-on-rails-example).
@@ -141,7 +145,7 @@ issue.
141
145
  * Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](docs/basics/configuration.md) for documentation of all configuration options.
142
146
  * Configure `config/webpacker.yml`. If you used the generator and the default webpacker setup, you don't need to touch this file. If you are customizing your setup, then consult the [spec/dummy/config/webpacker.yml](./spec/dummy/config/webpacker.yml) example or the official default [webpacker.yml](https://github.com/rails/webpacker/blob/master/lib/install/config/webpacker.yml).
143
147
  * Tip: set `compile: false` for development if you know that you'll always be compiling with a watch process. Otherwise, every request will check if compilation is needed.
144
- * Your `public_output_path` must match your Webpack configuration for `output` of your bundles.
148
+ * Your `public_output_path` must match your custom Webpack configuration for `output` of your bundles.
145
149
  * Only set `cache_manifest` to `true` in your production env.
146
150
 
147
151
  ## Including your React Component on your Rails Views
@@ -166,7 +170,7 @@ issue.
166
170
  ReactOnRails.register({ HelloWorld });
167
171
  ```
168
172
 
169
- 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.
173
+ 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. You may call `ReactOnRails.register` many times.
170
174
 
171
175
  - `@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:
172
176
 
@@ -175,7 +179,7 @@ issue.
175
179
  <%= react_component("HelloWorld", props: { name: "Stranger" }) %>
176
180
  ```
177
181
 
178
- - This is what your HelloWorld.js file might contain. The railsContext is always available for any parameters that you _always_ want available for your React components. It has _nothing_ to do with the concept of the [React Context](https://reactjs.org/docs/context.html). See [render functions and the RailsContext](docs/basics/render-functions-and-railscontext.md) for more details on this topic.
182
+ - This is what your HelloWorld.js file might contain. The railsContext is always available for any parameters that you _always_ want available for your React components. It has _nothing_ to do with the concept of the [React Context](https://reactjs.org/docs/context.html). See [Render-Functions and the RailsContext](docs/basics/render-functions-and-railscontext.md) for more details on this topic.
179
183
 
180
184
  ```js
181
185
  import React from 'react';
@@ -193,32 +197,6 @@ issue.
193
197
 
194
198
  See the [View Helpers API](./docs/api/view-helpers-api.md) for more details on `react_component` and its sibling function `react_component_hash`.
195
199
 
196
- ## Fragment Caching
197
-
198
- Fragment caching is a [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro) feature. Fragment caching is a **HUGE** performance booster for your apps. Use the `cached_react_component` and `cached_react_component_hash`. The API is the same as `react_component` and `react_component_hash`, but for 2 differences:
199
-
200
- 1. The `cache_key` takes the same parameters as any Rails `cache` view helper.
201
- 1. The **props** are passed via a block so that evaluation of the props is not done unless the cache is broken. Suppose you put your props calculation into some method called `some_slow_method_that_returns_props`:
202
-
203
- ```ruby
204
- <%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
205
- some_slow_method_that_returns_props
206
- end %>
207
- ```
208
-
209
- Such fragment caching saves a ton of CPU work for your web server and greatly reduces the request time. It completely skips the evaluation costs of:
210
-
211
- 1. Database calls to compute the props.
212
- 2. Serialization the props values hash into a JSON string for evaluating JavaScript to server render.
213
- 3. Costs associated with evaluating JavaScript from your Ruby code.
214
- 4. Creating the HTML string containing the props and the server-rendered JavaScript code.
215
-
216
- Note, even without server rendering (without step 3 above), fragment caching is still effective.
217
-
218
- ## Integration with Node.js for Server Rendering
219
-
220
- Default server rendering is done by ExecJS. If you want to use a Node.js server for better performing server rendering, [email justin@shakacode.com](mailto:justin@shakacode.com). ShakaCode has built a premium Node rendering server that is part of [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro).
221
-
222
200
  ## Globally Exposing Your React Components
223
201
 
224
202
  For the React on Rails view helper `react_component` to use your React components, you will have to **register** them in your JavaScript code.
@@ -246,15 +224,15 @@ For details on techniques to use different code for client and server rendering,
246
224
 
247
225
  You have two ways to specify your React components. You can either register the React component (either function or class component) directly, or you can create a function that returns a React component, which we using the name of a "render-function". Creating a render-function allows:
248
226
 
249
- 1. You have access to the `railsContext`. See documentation for the railsContext in terms of why you might need it. You **need** a render function to access the `railsContext`.
227
+ 1. You to have access to the `railsContext`. See [documentation for the railsContext](./docs/basics/render-functions-and-railscontext.md) in terms of why you might need it. You **need** a Render-Function to access the `railsContext`.
250
228
  2. You can use the passed-in props to initialize a redux store or set up react-router.
251
229
  3. You can return different components depending on what's in the props.
252
230
 
253
- Note, the return value of a **render function** should be either a React Function or Class Component, or an object representing server rendering results.
231
+ Note, the return value of a **Render-Function** should be either a React Function or Class Component, or an object representing server rendering results.
254
232
 
255
233
  Do not return a React Element (JSX).
256
234
 
257
- ReactOnRails will automatically detect a registered render function by the fact that the function takes
235
+ ReactOnRails will automatically detect a registered Render-Function by the fact that the function takes
258
236
  more than 1 parameter. In other words, if you want the ability to provide a function that returns the
259
237
  React component, then you need to specify at least a second parameter. This is the `railsContext`.
260
238
  If you're not using this parameter, declare your function with the unused param:
@@ -268,13 +246,13 @@ const MyComponentGenerator = (props, _railsContext) => {
268
246
  }
269
247
  ```
270
248
 
271
- Thus, there is no difference between registering a React function or class Component versus a "render function."
249
+ Thus, there is no difference between registering a React Function Component or class Component versus a "Render-Function." Just call `ReactOnRails.register`.
272
250
 
273
- ## react_component_hash for render functions
251
+ ## react_component_hash for Render-Functions
274
252
 
275
- Another reason to use a render 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`.
253
+ Another reason to use a Render-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`.
276
254
 
277
- For server rendering, if you wish to return multiple HTML strings from a render function, you may return an Object from your render 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:
255
+ For server rendering, if you wish to return multiple HTML strings from a Render-Function, you may return an Object from your Render-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:
278
256
 
279
257
  ```js
280
258
  { renderedHtml: { componentHtml, customKey1, customKey2} }
@@ -299,7 +277,6 @@ Browse the links in the [Summary Table of Contents](./SUMMARY.md)
299
277
  Here are some highly recommended next articles to read:
300
278
 
301
279
  1. [How React on Rails Works](docs/outdated/how-react-on-rails-works.md)
302
- 1. [Recommended Project Structure](./docs/basics/recommended-project-structure.md)
303
280
  1. [Webpack Configuration](./docs/basics/webpack-configuration.md)
304
281
  1. [View Helpers API](./docs/api/view-helpers-api.md)
305
282
  1. [Caching and Performance: React on Rails Pro](https://www.shakacode.com/react-on-rails-pro).
@@ -336,16 +313,42 @@ React on Rails Pro provides Node server rendering, fragment caching, code-splitt
336
313
 
337
314
  The [React on Rails Pro Support Plan](https://www.shakacode.com/react-on-rails-pro) can help!
338
315
 
339
- * Optimizing your webpack setup to Webpack v4 for React on Rails including code splitting with react-router v4, webpack v4, and react-loadable.
340
- * Upgrading your app to use the current Webpack setup that skips the Sprockets asset pipeline.
316
+ * Optimizing your webpack setup to the latest Webpack for React on Rails including code splitting with loadable-components.
317
+ * Upgrading your app to use the current `rails/webpacker` setup that skips the Sprockets asset pipeline.
341
318
  * Better performance client and server side.
342
- * Best practices based on over four years of React on Rails experience.
319
+ * Best practices based on over 6 years of React on Rails experience on many production projects.
343
320
  * Using [Reason](https://reasonml.github.io/) with (or without) React on Rails.
344
321
 
345
- ShakaCode can also help you with your custom software development needs. We specialize in marketplace and e-commerce applications that utilize both Rails and React. Because we own [HawaiiChee.com](https://www.hawaiichee.com), we can leverage that code for your app!
322
+ ShakaCode can also help you with your custom software development needs. We specialize in marketplace and e-commerce applications that utilize both Rails and React. Because we own [HiChee.com](https://hichee.com), we can leverage that code for your app!
346
323
 
347
324
  Please email Justin Gordon [justin@shakacode.com](mailto:justin@shakacode.com), the maintainer of React on Rails, for more information.
348
325
 
326
+ ### Fragment Caching
327
+
328
+ Fragment caching is a [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro) feature. Fragment caching is a **HUGE** performance booster for your apps. Use the `cached_react_component` and `cached_react_component_hash`. The API is the same as `react_component` and `react_component_hash`, but for 2 differences:
329
+
330
+ 1. The `cache_key` takes the same parameters as any Rails `cache` view helper.
331
+ 1. The **props** are passed via a block so that evaluation of the props is not done unless the cache is broken. Suppose you put your props calculation into some method called `some_slow_method_that_returns_props`:
332
+
333
+ ```ruby
334
+ <%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
335
+ some_slow_method_that_returns_props
336
+ end %>
337
+ ```
338
+
339
+ Such fragment caching saves CPU work for your web server and greatly reduces the request time. It completely skips the evaluation costs of:
340
+
341
+ 1. Database calls to compute the props.
342
+ 2. Serialization the props values hash into a JSON string for evaluating JavaScript to server render.
343
+ 3. Costs associated with evaluating JavaScript from your Ruby code.
344
+ 4. Creating the HTML string containing the props and the server-rendered JavaScript code.
345
+
346
+ Note, even without server rendering (without step 3 above), fragment caching is still effective.
347
+
348
+ ## Integration with Node.js for Server Rendering
349
+
350
+ Default server rendering is done by ExecJS. If you want to use a Node.js server for better performing server rendering, [email justin@shakacode.com](mailto:justin@shakacode.com). ShakaCode has built a premium Node rendering server that is part of [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro).
351
+
349
352
  ## Testimonials for ShakaCode
350
353
  [HVMN Testimonial, by Paul Benigeri, October 12, 2018](./docs/testimonials/hvmn.md)
351
354
  > The price we paid for the consultation + the React on Rails pro license has already been made back a couple of times from hosting fees alone. The entire process was super hands off, and our core team was able to focus on shipping new feature during that sprint.
data/SUMMARY.md CHANGED
@@ -8,7 +8,6 @@
8
8
  + [How React on Rails Works](docs/outdated/how-react-on-rails-works.md)
9
9
  + [Client vs. Server Rendering](./docs/basics/client-vs-server-rendering.md)
10
10
  + [React Server Rendering](./docs/basics/react-server-rendering.md)
11
- + [Recommended Project Structure](./docs/basics/recommended-project-structure.md)
12
11
  + [Render-Functions and the RailsContext](docs/basics/render-functions-and-railscontext.md)
13
12
  + [Caching and Performance: React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
14
13
  + [Deployment](docs/basics/deployment.md).
@@ -28,6 +27,7 @@
28
27
  + [Updating Dependencies](./docs/additional-reading/updating-dependencies.md)
29
28
  + [Manual Installation Overview](docs/outdated/manual-installation-overview.md)
30
29
  + [Upgrading from rails/webpacker v3 to v4](docs/additional-reading/upgrade-webpacker-v3-to-v4.md)
30
+ + [Recommended Project Structure](docs/additional-reading/recommended-project-structure.md)
31
31
 
32
32
  ## **Rails**
33
33
  + [Rails Engine Integration](./docs/additional-reading/rails-engine-integration.md)
@@ -0,0 +1,10 @@
1
+ # Converting from Custom Webpack Config to Rails Webpacker Config
2
+
3
+ 1. Compare your package.json and the dependencies in https://github.com/rails/webpacker/blob/master/package.json#L14-L48
4
+ and avoid any duplicates. We don't want different versions of the same packages.
5
+ We want the versions from rails/webpacker unless we specifically want to override them.
6
+ 2. Search the rails/webpacker repo for anything you're not sure about in terms of package names.
7
+ 3. run `bin/webpack` and make sure there are zero errors
8
+ 4. update webpack plugins and loaders to current or close to current
9
+ 5. Make sure that your bin/webpack and bin/webpacker match the latest on
10
+ https://github.com/rails/webpacker/tree/master/lib/install/bin
@@ -39,7 +39,7 @@ For a fleshed out integration of react_on_rails with react-router, check out [Re
39
39
 
40
40
  # Server Rendering Using React Router V4
41
41
 
42
- Your render function may not return an object with the property `renderedHtml`. Thus, you call
42
+ Your Render-Function may not return an object with the property `renderedHtml`. Thus, you call
43
43
  renderToString() and return an object with this property.
44
44
 
45
45
  This example **only applies to server rendering** and should be only used in the server side bundle.
@@ -0,0 +1,69 @@
1
+ # Recommended Project structure
2
+
3
+ The React on Rails generator uses the standard `rails/webpacker` convention of this structure:
4
+
5
+ ```yml
6
+ app/javascript:
7
+ ├── bundles:
8
+ │ # Logical groups of files that can be used for code splitting
9
+ │ └── hello-world-bundle.js
10
+ ├── packs:
11
+ │ # only webpack entry files here
12
+ │ └── hello-world-bundle.js
13
+ ```
14
+
15
+ Per the example repo [shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh](https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh),
16
+ you should consider keeping your codebase mostly consistent with the defaults for [rails/webpacker](https://github.com/rails/webpacker).
17
+
18
+ ## Steps to convert from the generator defaults to use a `/client` directory for source code
19
+
20
+ 1. Move the directory:
21
+
22
+ ```
23
+ mv app/javascript client
24
+ ```
25
+
26
+ 2. Edit your `/config/webpacker.yml` file. Change the `default/source_path`:
27
+
28
+ ```yml
29
+ source_path: client
30
+ ```
31
+
32
+ ## Moving node_modules from `/` to `/client` with a custom webpack setup.
33
+
34
+ `rails/webpacker` probably doesn't support having your main node_modules directory under `/client`, so only follow these steps if you want to use your own webpack configuration.
35
+
36
+ 1. Move the `/package.json` to `/client/package.json`
37
+ 2. Create a `/package.json` that delegates to `/client/package.json`.
38
+ ```
39
+ "scripts": {
40
+ "heroku-postbuild": "cd ./client && yarn"
41
+ },
42
+ ```
43
+ 3. If your node_modules directory is not at the top level of the Rails project, then you will need to set the
44
+ ENV value of WEBPACKER_CONFIG to the location of the `config/webpacker.yml` file per [rails/webpacker PR 2561](https://github.com/rails/webpacker/pull/2561).
45
+
46
+ ## CSS, Sass, Fonts, and Images
47
+ Should you move your styling assets to Webpack? Or stick with the plain Rails asset pipeline. It depends!
48
+
49
+ Here's a good discussion of this option: [Why does Rails 6 include both Webpacker and Sprockets?](https://rossta.net/blog/why-does-rails-install-both-webpacker-and-sprockets.html).
50
+
51
+ You have 2 basic choices:
52
+
53
+ ### Simple Rails Way
54
+ This isn't really any technique, as you keep handling all your styling assets using Rails standard tools, such as using the [sass-rails gem](https://rubygems.org/gems/sass-rails/versions/5.0.4). Basically, Webpack doesn't get involved with styling. Your Rails layouts just doing the styling the standard Rails way.
55
+
56
+ #### Advantages to the Simple Rails Way
57
+ 1. Much simpler! There's no changes really from your current processes.
58
+
59
+ ### Using Webpack to Manage Styling Assets
60
+ This technique involves customization of the webpack config files to generate CSS, image, and font assets.
61
+
62
+ #### Directory structure
63
+ 1. `/client/app/assets`: Assets for CSS for client app.
64
+ 1. `/client/app/assets/fonts` and `/client/app/assets/styles`: Globally shared assets for styling. Note, most Sass and image assets will be stored next to the JavaScript files.
65
+
66
+ #### Advantages to having Webpack Manage Styles
67
+ 1. You can use [CSS modules](https://github.com/css-modules/css-modules), which is super compelling once you seen the benefits.
68
+ 1. You can use CSS in JS.
69
+ 1. You can do hot reloading of your assets. Thus, you do not have to refresh your web page to see asset change, including changing styles.
@@ -13,7 +13,7 @@ Be sure to use mini_racer. See [issues/428](https://github.com/shakacode/react_o
13
13
  - You can conditionally avoid running code that references document by either checking if `window`
14
14
  is defined or using the "railsContext"
15
15
  your top level react component. Since the passed in props Hash from the view helper applies to
16
- client and server side code, the best way to do this is to use a render function.
16
+ client and server side code, the best way to do this is to use a Render-Function.
17
17
  - If you're serious about server rendering, it's worth the effort to have different entry points for client and server rendering. It's worth the extra complexity. The point is that you have separate files for top level client or server side, and you pass some extra option indicating that rendering is happening server side.
18
18
  - You can enable Node.js server rendering via [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
19
19
 
@@ -22,6 +22,9 @@ Be sure to use mini_racer. See [issues/428](https://github.com/shakacode/react_o
22
22
  1. First be sure your code works with server rendering disabled (`prerender: false`)
23
23
  2. Be sure that `config.trace` is true. You will get the server invocation code that renders your component. If you're not using Webpacker, you will also get the whole file used to setup the JavaScript context.
24
24
 
25
+ ## CSS
26
+ Server bundles must always have CSS Extracted
27
+
25
28
  ## setTimeout, setInterval, and clearTimeout
26
29
 
27
30
  These methods are polyfilled for server rendering to be no-ops. We log calls to these when in `trace` mode. In the past, some libraries, namely babel-polyfill, did call setTimout.
@@ -25,10 +25,10 @@ The best source of docs is the main [ReactOnRails.js](https://github.com/shakaco
25
25
  /**
26
26
  * Main entry point to using the react-on-rails npm package. This is how Rails will be able to
27
27
  * find you components for rendering. Components get called with props, or you may use a
28
- * "render function" to return a React component or an object with the following shape:
28
+ * "Render-Function" to return a React component or an object with the following shape:
29
29
  * { renderedHtml, redirectLocation, error }.
30
- * For server rendering, if you wish to return multiple HTML strings from a render function,
31
- * you may return an Object from your render function with a single top level property of
30
+ * For server rendering, if you wish to return multiple HTML strings from a Render-Function,
31
+ * you may return an Object from your Render-Function with a single top level property of
32
32
  * renderedHtml. Inside this Object, place a key called componentHtml, along with any other
33
33
  * needed keys. This is useful when you using side effects libraries like react helmet.
34
34
  * Your Ruby code with get this Object as a Hash containing keys componentHtml and any other
@@ -1,10 +1,10 @@
1
1
  # Redux Store
2
2
 
3
- _This redux API is no longer recommended as it prevents dynamic code splitting for performance. Instead, you should use the standard react_component view helper passing in a "render function."_
3
+ _This redux API is no longer recommended as it prevents dynamic code splitting for performance. Instead, you should use the standard react_component view helper passing in a "Render-Function."_
4
4
 
5
5
  You don't need to use the `redux_store` api to use redux. This api was setup to support multiple calls to `react_component` on one page that all talk to the same redux store.
6
6
 
7
- If you are only rendering one react component on a page, as is typical to do a "Single Page App" in React, then you should _probably_ pass the props to your React component in a "render function."
7
+ If you are only rendering one react component on a page, as is typical to do a "Single Page App" in React, then you should _probably_ pass the props to your React component in a "Render-Function."
8
8
 
9
9
  Consider using the `redux_store` helper for the two following use cases:
10
10
 
@@ -22,7 +22,7 @@ Uncommonly used options:
22
22
  id: nil,
23
23
  ```
24
24
 
25
- - **component_name:** Can be a React component, created using an ES6 class or a render function that returns a React component (or, only on the server side, an object with shape { redirectLocation, error, renderedHtml }), or a "renderer function" that manually renders a React component to the dom (client side only).
25
+ - **component_name:** Can be a React component, created using a React Function Component, an ES6 class or a Render-Function that returns a React component (or, only on the server side, an object with shape { redirectLocation, error, renderedHtml }), or a "renderer function" that manually renders a React component to the dom (client side only). Note, a "renderer function" is a special type of "Render-Function." A "renderer function" takes a 3rd param of a DOM ID.
26
26
  All options except `props, id, html_options` will inherit from your `react_on_rails.rb` initializer, as described [here](../basics/configuration.md).
27
27
  - **general options:**
28
28
  - **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.
@@ -45,7 +45,7 @@ adding meta-tags to a page. It is exactly like react_component except for the fo
45
45
 
46
46
  1. `prerender: true` is automatically added to options, as this method doesn't make sense for
47
47
  client only rendering.
48
- 2. Your JavaScript render function for server rendering must return an Object rather than a React Component.
48
+ 2. Your JavaScript Render-Function for server rendering must return an Object rather than a React Component.
49
49
  3. Your view code must expect an object and not a string.
50
50
 
51
51
  Here is an example of ERB view code:
@@ -98,11 +98,11 @@ You can call `rails_context` or `rails_context(server_side: true|false)` from yo
98
98
 
99
99
  ### Renderer Functions (function that will call ReactDOM.render or ReactDOM.hydrate)
100
100
 
101
- A "renderer function" is a render function that accepts three arguments (rather than 2): `(props, railsContext, domNodeId) => { ... }`. Instead of returning a React component, a renderer is responsible for installing a callback that will call `ReactDOM.render` (in React 16+, `ReactDOM.hydrate`) to render a React component into the DOM. The "renderer function" is called at the same time the document ready event would instantate the React components into the DOM.
101
+ A "renderer function" is a Render-Function that accepts three arguments (rather than 2): `(props, railsContext, domNodeId) => { ... }`. Instead of returning a React component, a renderer is responsible for installing a callback that will call `ReactDOM.render` (in React 16+, `ReactDOM.hydrate`) to render a React component into the DOM. The "renderer function" is called at the same time the document ready event would instantate the React components into the DOM.
102
102
 
103
103
  Why would you want to call `ReactDOM.hydrate` yourself? One possible use case is [code splitting](docs/outdated/code-splitting.md). In a nutshell, you don't want to load the React component on the DOM node yet. So you want to install some handler that will call `ReactDOM.hydrate` at a later time. In the case of code splitting with server rendering, the server rendered code has any async code loaded and used to server render. Thus, the client code must also fully load any asynch code before server rendering. Otherwise, the client code would first render partially, not matching the server rendering, and then a second later, the full code would render, resulting in an unpleasant flashing on the screen.
104
104
 
105
- Renderer functions are not meant to be used on the server since there's no DOM on the server. Instead, use a render function. Attempting to server render with a renderer function will throw an error.
105
+ Renderer functions are not meant to be used on the server since there's no DOM on the server. Instead, use a Render-Function. Attempting to server render with a renderer function will throw an error.
106
106
 
107
107
  ------------
108
108
 
@@ -1,5 +1,7 @@
1
1
  # Client-Side Rendering vs. Server-Side Rendering
2
2
 
3
+ *See also [react-server-rendering.md](./react-server-rendering.md).*
4
+
3
5
  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`.
4
6
 
5
7
  Now the server will interpret your JavaScript. The default is to use [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.
@@ -215,7 +215,7 @@ Example of a RenderingExtension for custom values in the `rails_context`:
215
215
  module RenderingExtension
216
216
 
217
217
  # Return a Hash that contains custom values from the view context that will get merged with
218
- # the standard rails_context values and passed to all calls to render functions used by the
218
+ # the standard rails_context values and passed to all calls to Render-Functions used by the
219
219
  # react_component and redux_store view helpers
220
220
  def self.custom_context(view_context)
221
221
  {