react_on_rails 11.3.1 → 12.0.0.pre.beta.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (87) hide show
  1. checksums.yaml +4 -4
  2. data/.circleci/config.yml +320 -0
  3. data/.eslintignore +2 -1
  4. data/.eslintrc +23 -1
  5. data/.github/FUNDING.yml +1 -0
  6. data/.gitignore +3 -1
  7. data/.prettierignore +10 -1
  8. data/.prettierrc +3 -0
  9. data/.rubocop.yml +37 -11
  10. data/.travis.yml +9 -20
  11. data/CHANGELOG.md +44 -19
  12. data/CONTRIBUTING.md +60 -71
  13. data/Gemfile +3 -4
  14. data/{COMM-LICENSE → REACT-ON-RAILS-PRO-LICENSE} +6 -9
  15. data/README.md +102 -69
  16. data/Rakefile +0 -7
  17. data/SUMMARY.md +7 -11
  18. data/book.json +5 -5
  19. data/docs/additional-reading/asset-pipeline.md +8 -16
  20. data/docs/additional-reading/react-helmet.md +30 -10
  21. data/docs/additional-reading/react-router.md +52 -75
  22. data/docs/additional-reading/server-rendering-tips.md +12 -7
  23. data/docs/api/javascript-api.md +3 -3
  24. data/docs/api/redux-store-api.md +4 -2
  25. data/docs/api/view-helpers-api.md +6 -7
  26. data/docs/basics/configuration.md +60 -57
  27. data/docs/basics/deployment.md +1 -2
  28. data/docs/basics/i18n.md +44 -22
  29. data/docs/basics/installation-into-an-existing-rails-app.md +2 -2
  30. data/docs/basics/react-server-rendering.md +1 -1
  31. data/docs/basics/{generator-functions-and-railscontext.md → render-functions-and-railscontext.md} +59 -21
  32. data/docs/basics/upgrading-react-on-rails.md +50 -2
  33. data/docs/basics/webpack-configuration.md +15 -1
  34. data/docs/contributor-info/errors-with-hooks.md +45 -0
  35. data/docs/contributor-info/pull-requests.md +44 -0
  36. data/docs/misc/doctrine.md +1 -1
  37. data/docs/{misc-pending → outdated}/code-splitting.md +12 -8
  38. data/docs/{additional-reading → outdated}/heroku-deployment.md +0 -6
  39. data/docs/{basics → outdated}/how-react-on-rails-works.md +2 -2
  40. data/docs/{misc-pending → outdated}/manual-installation-overview.md +5 -5
  41. data/docs/{additional-reading → outdated}/rails-assets-relative-paths.md +3 -3
  42. data/docs/{misc-pending → outdated}/rails-assets.md +4 -7
  43. data/docs/{misc → outdated}/rails3.md +0 -0
  44. data/docs/tutorial.md +54 -34
  45. data/jest.config.js +4 -0
  46. data/lib/generators/react_on_rails/dev_tests_generator.rb +1 -1
  47. data/lib/generators/react_on_rails/generator_helper.rb +4 -6
  48. data/lib/generators/react_on_rails/templates/base/base/app/javascript/bundles/HelloWorld/components/HelloWorld.jsx +9 -8
  49. data/lib/generators/react_on_rails/templates/dev_tests/spec/rails_helper.rb +1 -8
  50. data/lib/generators/react_on_rails/templates/redux/base/app/javascript/bundles/HelloWorld/components/HelloWorld.jsx +4 -8
  51. data/lib/generators/react_on_rails/templates/redux/base/app/javascript/bundles/HelloWorld/store/helloWorldStore.js +1 -3
  52. data/lib/react_on_rails.rb +3 -1
  53. data/lib/react_on_rails/configuration.rb +13 -22
  54. data/lib/react_on_rails/error.rb +2 -0
  55. data/lib/react_on_rails/helper.rb +41 -91
  56. data/lib/react_on_rails/json_parse_error.rb +2 -0
  57. data/lib/react_on_rails/locales/base.rb +142 -0
  58. data/lib/react_on_rails/locales/to_js.rb +37 -0
  59. data/lib/react_on_rails/locales/to_json.rb +27 -0
  60. data/lib/react_on_rails/prerender_error.rb +11 -15
  61. data/lib/react_on_rails/server_rendering_pool/ruby_embedded_java_script.rb +41 -46
  62. data/lib/react_on_rails/test_helper/ensure_assets_compiled.rb +7 -8
  63. data/lib/react_on_rails/utils.rb +14 -19
  64. data/lib/react_on_rails/version.rb +1 -1
  65. data/lib/react_on_rails/version_checker.rb +1 -0
  66. data/lib/react_on_rails/webpacker_utils.rb +13 -2
  67. data/lib/tasks/assets.rake +5 -45
  68. data/lib/tasks/locale.rake +8 -2
  69. data/package-scripts.yml +11 -8
  70. data/package.json +29 -28
  71. data/rakelib/dummy_apps.rake +1 -9
  72. data/rakelib/example_type.rb +3 -1
  73. data/rakelib/examples.rake +3 -0
  74. data/rakelib/lint.rake +2 -7
  75. data/rakelib/node_package.rake +2 -2
  76. data/rakelib/run_rspec.rake +5 -18
  77. data/react_on_rails.gemspec +3 -5
  78. data/tsconfig.json +14 -0
  79. data/webpackConfigLoader.js +3 -2
  80. data/yarn.lock +4170 -2197
  81. metadata +30 -55
  82. data/Gemfile.rails32 +0 -73
  83. data/docs/additional-reading/babel.md +0 -5
  84. data/docs/additional-reading/hot-reloading-rails-development-asset-pipeline.md +0 -47
  85. data/docs/api/ruby-api-hot-reload-view-helpers.md +0 -44
  86. data/lib/react_on_rails/assets_precompile.rb +0 -153
  87. data/lib/react_on_rails/locales_to_js.rb +0 -138
@@ -59,58 +59,12 @@ ReactOnRails.configure do |config|
59
59
 
60
60
  # defaults to "" (top level)
61
61
  #
62
- config.node_modules_location = "client" # Recommended!
62
+ config.node_modules_location = "client" # If using webpacker you should use "".
63
63
 
64
64
  # This configures the script to run to build the production assets by webpack. Set this to nil
65
65
  # if you don't want react_on_rails building this file for you.
66
66
  config.build_production_command = "RAILS_ENV=production bin/webpack"
67
67
 
68
- ################################################################################
69
- ################################################################################
70
- # TEST CONFIGURATION OPTIONS
71
- # Below options are used with the use of this test helper:
72
- # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
73
- ################################################################################
74
-
75
- # If you are using this in your spec_helper.rb (or rails_helper.rb):
76
- #
77
- # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
78
- #
79
- # with rspec then this controls what yarn command is run
80
- # to automatically refresh your webpack assets on every test run.
81
- #
82
- config.build_test_command = "RAILS_ENV=test bin/webpack"
83
-
84
- # Directory where your generated assets go. All generated assets must go to the same directory.
85
- # If you are using webpacker, this value will come from your config/webpacker.yml file.
86
- # This is the default in webpacker.yml:
87
- # public_output_path: packs-test
88
- # which means files in /public/packs-test
89
- #
90
- # Alternately, you may configure this if you are NOT using webpacker. It is relative to your Rails
91
- # root directory. A custom, non-webpacker, config might use something like:
92
- #
93
- # config.generated_assets_dir = File.join(%w[public webpack], Rails.env)
94
- # This setting should not be used if using webpacker.
95
-
96
- # CONFIGURE YOUR SOURCE FILES
97
- # The test helper needs to know where your JavaScript files exist. The default is configured
98
- # by your config/webpacker.yml soure_path:
99
- # source_path: client/app/javascript # if using recommended /client directory
100
- #
101
- # If you are not using webpacker, the `node_modules_location` is assumed to be the location of your source
102
- # files.
103
-
104
- # Define the files we need to check for webpack compilation when running tests.
105
- # The default is `%w( manifest.json )` as will be sufficient for most webpacker builds.
106
- # However, if you are generated a server bundle that is NOT hashed (present in manifest.json),
107
- # then include the file in this list like this:
108
- #
109
- config.webpack_generated_files = %w( server-bundle.js manifest.json )
110
-
111
- # You can optionally add values to your rails_context. See example below for RenderingExtension
112
- # config.rendering_extension = RenderingExtension
113
-
114
68
  ################################################################################
115
69
  ################################################################################
116
70
  # SERVER RENDERING OPTIONS
@@ -127,27 +81,35 @@ ReactOnRails.configure do |config|
127
81
  # you should include a name that matches your bundle name in your webpack config.
128
82
  config.server_bundle_js_file = "server-bundle.js"
129
83
 
84
+ # THE BELOW OPTIONS FOR SERVER-SIDE RENDERING RARELY NEED CHANGING
85
+ #
86
+ # This value only affects server-side rendering when using the webpack-dev-server
87
+ # If you are hashing the server bundle and you want to use the same bundle for client and server,
88
+ # you'd set this to `true` so that React on Rails reads the server bundle from the webpack-dev-server.
89
+ # Normally, you have different bundles for client and server, thus, the default is false.
90
+ # Furthermore, if you are not hashing the server bundle (not in the manifest.json), then React on Rails
91
+ # will only look for the server bundle to be created in the typical file location, typically by
92
+ # a `webpack --watch` process.
93
+ config.same_bundle_for_client_and_server = false
94
+
130
95
  # If set to true, this forces Rails to reload the server bundle if it is modified
131
96
  # Default value is Rails.env.development?
132
- #
97
+ # You probably will never change this.
133
98
  config.development_mode = Rails.env.development?
134
99
 
135
- # For server rendering so that it replays in the browser console.
100
+ # For server rendering so that the server-side console replays in the browser console.
136
101
  # This can be set to false so that server side messages are not displayed in the browser.
137
- # Default is true. Be cautious about turning this off.
102
+ # Default is true. Be cautious about turning this off, as it can make debugging difficult.
138
103
  # Default value is true
139
- #
140
104
  config.replay_console = true
141
105
 
142
106
  # Default is true. Logs server rendering messages to Rails.logger.info. If false, you'll only
143
107
  # see the server rendering messages in the browser console.
144
- #
145
108
  config.logging_on_server = true
146
109
 
147
110
  # Default is true only for development? to raise exception on server if the JS code throws for
148
111
  # server rendering. The reason is that the server logs will show the error and force you to fix
149
112
  # any server rendering issues immediately during development.
150
- #
151
113
  config.raise_on_prerender_error = Rails.env.development?
152
114
 
153
115
  ################################################################################
@@ -181,6 +143,10 @@ ReactOnRails.configure do |config|
181
143
  # and installed gems are loaded
182
144
  config.i18n_yml_dir = Rails.root.join("config", "locales", "client")
183
145
 
146
+ # Possible output formats are js and json
147
+ # The default format is json
148
+ config.i18n_output_format = 'js'
149
+
184
150
  ################################################################################
185
151
  ################################################################################
186
152
  # CLIENT RENDERING OPTIONS
@@ -189,8 +155,47 @@ ReactOnRails.configure do |config|
189
155
  ################################################################################
190
156
  # default is false
191
157
  config.prerender = false
192
- end
193
158
 
159
+ # You can optionally add values to your rails_context. This object is passed
160
+ # every time a component renders.
161
+ # See example below for an example definition of RenderingExtension
162
+ #
163
+ # config.rendering_extension = RenderingExtension
164
+
165
+ ################################################################################
166
+ ################################################################################
167
+ # TEST CONFIGURATION OPTIONS
168
+ # Below options are used with the use of this test helper:
169
+ # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
170
+ #
171
+ # NOTE:
172
+ # Instead of using this test helper, you may ensure fresh test files using rails/webpacker via:
173
+ # 1. Have `config/webpacker/test.js` exporting an array of objects to configure both client and server bundles.
174
+ # 2. Set the compile option to true in config/webpacker.yml for env test
175
+ ################################################################################
176
+
177
+ # If you are using this in your spec_helper.rb (or rails_helper.rb):
178
+ #
179
+ # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
180
+ #
181
+ # with rspec then this controls what yarn command is run
182
+ # to automatically refresh your webpack assets on every test run.
183
+ #
184
+ config.build_test_command = "RAILS_ENV=test bin/webpack"
185
+
186
+ # CONFIGURE YOUR SOURCE FILES
187
+ # The test helper needs to know where your JavaScript files exist. The value is configured
188
+ # by your config/webpacker.yml source_path:
189
+ # source_path: client/app/javascript # if using recommended /client directory
190
+ #
191
+ # Define the files we need to check for webpack compilation when running tests.
192
+ # The default is `%w( manifest.json )` as will be sufficient for most webpacker builds.
193
+ # However, if you are generated a server bundle that is NOT hashed (present in manifest.json),
194
+ # then include the file in this list like this:
195
+ config.webpack_generated_files = %w( server-bundle.js manifest.json )
196
+ # Note, be sure NOT to include your server-bundle.js if it is hashed, or else React on Rails will
197
+ # think the server-bundle.js is missing every time for test runs.
198
+ end
194
199
  ```
195
200
 
196
201
  Example of a RenderingExtension for custom values in the `rails_context`:
@@ -199,7 +204,7 @@ Example of a RenderingExtension for custom values in the `rails_context`:
199
204
  module RenderingExtension
200
205
 
201
206
  # Return a Hash that contains custom values from the view context that will get merged with
202
- # the standard rails_context values and passed to all calls to generator functions used by the
207
+ # the standard rails_context values and passed to all calls to render functions used by the
203
208
  # react_component and redux_store view helpers
204
209
  def self.custom_context(view_context)
205
210
  {
@@ -208,5 +213,3 @@ module RenderingExtension
208
213
  end
209
214
  end
210
215
  ```
211
-
212
-
@@ -2,5 +2,4 @@
2
2
 
3
3
  - 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](./configuration.md).
4
4
  - `build_production_command`: Set to nil to turn off the precompilation of the js assets.
5
- - `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.
6
- - See the [Heroku Deployment](../additional-reading/heroku-deployment.md) doc for specifics regarding Heroku. The information for Heroku may apply to other deployments.
5
+ - See the [Heroku Deployment](docs/outdated/heroku-deployment.md) doc for specifics regarding Heroku. The information for Heroku may apply to other deployments.
@@ -1,23 +1,10 @@
1
- # How to add I18n
1
+ # I18n
2
2
 
3
3
  Here's a summary of adding the I18n functionality.
4
4
 
5
- You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and [PR #340](https://github.com/shakacode/react-webpack-rails-tutorial/pull/340), [commmited](https://github.com/shakacode/react-webpack-rails-tutorial/commit/ef369ed9d922aea5116ca7e50208169fd7831389) for a complete example.
5
+ 1. Add `config.i18n_dir` in `config/initializers/react_on_rails.rb`
6
6
 
7
- 1. Add `react-intl` & `intl` to `client/package.json`, and remember to `bundle && yarn install`.
8
-
9
- ```js
10
- "dependencies": {
11
- ...
12
- "intl": "^1.2.5",
13
- "react-intl": "^2.1.5",
14
- ...
15
- }
16
- ```
17
-
18
- 2. Add `config.i18n_dir` in `config/initializers/react_on_rails.rb`
19
-
20
- `react-intl` requires locale files in json format. React on Rails will generate `translations.js` & `default.js` automatically after you configured your `config.i18n_dir` in `config/initializers/react_on_rails.rb`.
7
+ React on Rails will generate `translations.json` & `default.json` automatically (see #3) after you configured your `config.i18n_dir` in `config/initializers/react_on_rails.rb`.
21
8
 
22
9
  ```ruby
23
10
  # Replace the following line to the location where you keep translation.js & default.js.
@@ -31,16 +18,49 @@ You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/rea
31
18
  config.i18n_yml_dir = Rails.root.join("PATH_TO", "YOUR_YAML_I18N_FOLDER")
32
19
  ```
33
20
 
34
- `translations.js`: All your locales in json format.
35
- `default.js`: Default settings in json format.
21
+ `translations.json`: All your locales in json format.
22
+ `default.json`: Default settings in json format.
36
23
 
37
- 3. Add `translations.js` and `default.js` to your `.gitignore` and `.eslintignore`.
24
+ 2. Add `translations.json` and `default.json` to your `.gitignore`.
25
+
26
+ 3. Javascript locale files must be generated before `yarn build`.
27
+
28
+ Once you setup `config.i18n_dir` as in the previous step, react_on_rails will automatically do this for testing (if using the `ReactOnRails::TestHelper.configure_rspec_to_compile_assets` and for production deployments if using the [default precompile rake hook](docs/outdated/heroku-deployment.md).
29
+
30
+ For development, you should adjust your startup scripts (Procfiles) so that they run **`bundle exec rake react_on_rails:locale`** before running any webpack watch process (`yarn run build:development`).
31
+
32
+ You may need to configure your CI to run **`bundle exec rake react_on_rails:locale`** before any webpack process if you are not using the React on Rails test helper.
33
+
34
+ Note, if you are try to lint before running tests, and you are depending on the test helper to build your locales, your linting will fail because the translations won't be built yet.
35
+
36
+ The fix is either to
37
+ 1) run the rake task to build the translations before running the lint command or
38
+ 2) to run the tests first.
39
+
40
+ # Generate locales with react-intl support
41
+
42
+ By default the locales generated in json format. If you need to generate files in the prior way
43
+ with `react-intl` supported via js files:
38
44
 
39
- 4. Javascript locale files must be generated before `yarn build`.
45
+ 1. Specify i18n output format in `react_on_rails.rb`:
46
+ ```rb
47
+ config.i18n_output_format = 'js'
48
+ ```
49
+
50
+ 2. Add `react-intl` & `intl` to `client/package.json`, and remember to `bundle && yarn install`.
51
+
52
+ ```js
53
+ "dependencies": {
54
+ ...
55
+ "intl": "^1.2.5",
56
+ "react-intl": "^2.1.5",
57
+ ...
58
+ }
59
+ ```
40
60
 
41
- Once you setup `config.i18n_dir` as in the previous step, react_on_rails will automatically do this for testing (if using the `ReactOnRails::TestHelper.configure_rspec_to_compile_assets` and for production deployments if using the [default precompile rake hook](../additional-reading/heroku-deployment.md). For development, you should adjust your startup scripts (Procfiles) so that they run **`bundle exec rake react_on_rails:locale`** before running any webpack watch process (`yarn run build:development`). You may need to configure your CI to run **`bundle exec rake react_on_rails:locale`** before any webpack process if you are not using the React on Rails test helper. Note, if you are try to lint before running tests, and you are depending on the test helper to build your locales, your linting will fail because the translations won't be built yet. The fix is either to 1) run the rake task to build the translations before running the lint command or 2) to run the tests first.
61
+ 3. Add `translations.js` and `default.js` to your `.gitignore` and `.eslintignore`.
42
62
 
43
- 5. In React, you need to initialize `react-intl`, and set parameters for it.
63
+ 4. In React, you need to initialize `react-intl`, and set parameters for it.
44
64
 
45
65
  ```js
46
66
  ...
@@ -74,4 +94,6 @@ You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/rea
74
94
 
75
95
  # Notes
76
96
 
97
+ * See why using JSON could be better compare to JS if amount of data is hure [ https://v8.dev/blog/cost-of-javascript-2019#json]( https://v8.dev/blog/cost-of-javascript-2019#json).
77
98
  * See [Support for Rails' i18n pluralization #1000](https://github.com/shakacode/react_on_rails/issues/1000) for a discussion of issues around pluralization.
99
+ * [Outdated] You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and [PR #340](https://github.com/shakacode/react-webpack-rails-tutorial/pull/340), [commmited](https://github.com/shakacode/react-webpack-rails-tutorial/commit/ef369ed9d922aea5116ca7e50208169fd7831389) for a complete example.
@@ -11,7 +11,7 @@
11
11
  gem "webpacker", "~> 3" # Newer versions might be supported
12
12
  ```
13
13
 
14
- 2. Run the following 2 commands to install Webpacker with React. Note, f you are using an older version of Rails than 5.1, you'll need to install webpacker with React per the instructions [here](https://github.com/rails/webpacker).
14
+ 2. Run the following 2 commands to install Webpacker with React. Note, if you are using an older version of Rails than 5.1, you'll need to install webpacker with React per the instructions [here](https://github.com/rails/webpacker).
15
15
 
16
16
 
17
17
  ```bash
@@ -45,7 +45,7 @@
45
45
 
46
46
  ## Installation
47
47
 
48
- See the [Installation Overview](../misc-pending/manual-installation-overview.md) for a concise set summary of what's in a React on Rails installation.
48
+ See the [Installation Overview](docs/outdated/manual-installation-overview.md) for a concise set summary of what's in a React on Rails installation.
49
49
 
50
50
 
51
51
  ## NPM
@@ -10,7 +10,7 @@ During the Rails rendering of HTML per a browser request, the Rails server will
10
10
 
11
11
  The default JavaScript interpretter is [ExecJS](https://github.com/rails/execjs). If you want to maximize the perfomance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki).
12
12
 
13
- See [this note](./how-react-on-rails-works.md#client-side-rendering-vs-server-side-rendering)
13
+ See [this note](docs/outdated/how-react-on-rails-works.md#client-side-rendering-vs-server-side-rendering)
14
14
 
15
15
 
16
16
  ## How do you do Server Rendering with React on Rails?
@@ -1,45 +1,80 @@
1
- # Generator Functions and Rails Context
1
+ # Render-Functions and the Rails Context
2
2
 
3
- ## Generator Functions
3
+ ## Render-Functions
4
4
 
5
- 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:
5
+ When you use a render-function to create react components (or renderedHtml on the server), or you
6
+ used shared redux stores, you get two params passed to your function that creates a React component:
6
7
 
7
8
  1. `props`: Props that you pass in the view helper of either `react_component` or `redux_store`
8
- 2. `railsContext`: Rails contextual information, such as the current pathname. You can customize this in your config file. **Note**: The `railsContext` is not related to the concept of a ["context" for React components](https://facebook.github.io/react/docs/context.html#how-to-use-context).
9
+ 2. `railsContext`: Rails contextual information, such as the current pathname. You can customize
10
+ this in your config file. **Note**: The `railsContext` is not related to the concept of a
11
+ ["context" for React components](https://facebook.github.io/react/docs/context.html#how-to-use-context).
9
12
 
10
- This parameters (`props` and `railsContext`) will be the same regardless of either client or server side rendering, except for the key `serverSide` based on whether or not you are server rendering.
13
+ These parameters (`props` and `railsContext`) will be the same regardless of either client or server
14
+ side rendering, except for the key `serverSide` based on whether or not you are server rendering.
11
15
 
12
- While you could manually configure your Rails code to pass the "`railsContext` information" with the rest of your "props", the `railsContext` is a convenience because it's passed consistently to all invocations of generator functions.
16
+ While you could manually configure your Rails code to pass the "`railsContext` information" with
17
+ the rest of your "props", the `railsContext` is a convenience because it's passed consistently to
18
+ all invocations of render functions.
13
19
 
14
- For example, suppose you create a "generator function" called MyAppComponent.
20
+ For example, suppose you create a "render-function" called MyAppComponent.
15
21
 
16
22
  ```js
17
23
  import React from 'react';
18
24
  const MyAppComponent = (props, railsContext) => (
19
- <div>
20
- <p>props are: {JSON.stringify(props)}</p>
21
- <p>railsContext is: {JSON.stringify(railsContext)}
22
- </p>
23
- </div>
25
+ // NOTE: need to wrap in a function so this is proper React function component that can use
26
+ // hooks
27
+
28
+ // the props get passed again, but we ignore since we use a closure
29
+ // or should we
30
+ () =>
31
+ <div>
32
+ <p>props are: {JSON.stringify(props)}</p>
33
+ <p>railsContext is: {JSON.stringify(railsContext)}
34
+ </p>
35
+ </div>
24
36
  );
25
37
  export default MyAppComponent;
26
38
  ```
27
39
 
40
+ ------------------------------
41
+
42
+ _This would be alternate API where you have to call React.createElement and the React on Rails code doesn't do that._
43
+
44
+ ```js
45
+ import React from 'react';
46
+ const MyAppComponent = (props, railsContext) => (
47
+ // NOTE: need to wrap in a function so this is proper React function component that can use
48
+ // hooks
49
+ React.createElement(
50
+ () =>
51
+ <div>
52
+ <p>props are: {JSON.stringify(props)}</p>
53
+ <p>railsContext is: {JSON.stringify(railsContext)}
54
+ </p>
55
+ </div>,
56
+ props)
57
+ );
58
+ export default MyAppComponent;
59
+ ```
60
+
61
+ ------------------------------------
62
+
28
63
  *Note: you will get a React browser console warning if you try to serverRender this since the value of `serverSide` will be different for server rendering.*
29
64
 
30
- So if you register your generator function `MyAppComponent`, it will get called like:
65
+ So if you register your render-function `MyAppComponent`, it will get called like:
31
66
 
32
67
  ```js
33
68
  reactComponent = MyAppComponent(props, railsContext);
34
69
  ```
35
70
 
36
- and, similarly, any redux store always initialized with 2 parameters:
71
+ and, similarly, any redux store is always initialized with 2 parameters:
37
72
 
38
73
  ```js
39
74
  reduxStore = MyReduxStore(props, railsContext);
40
75
  ```
41
76
 
42
- Note: you never make these calls. React on Rails makes these calls when it does either client or server rendering. You will define functions that take these 2 params and return a React component or a Redux Store. Naturally, you do not have to use second parameter of the railsContext if you do not need it.
77
+ Note: you never make these calls. React on Rails makes these calls when it does either client or server rendering. You will define functions that take these 2 params and return a React component or a Redux Store. Naturally, you do not have to use second parameter of the railsContext if you do not need it. If you don't take a second parameter, then you're probably defining a React function component and you will simply return a React Element, often just JSX.
43
78
 
44
79
  (Note: see below [section](#multiple-react-components-on-a-page-with-one-store) on how to setup redux stores that allow multiple components to talk to the same store.)
45
80
 
@@ -76,7 +111,7 @@ Plus, you can add your customizations to this. See "rendering extension" below.
76
111
 
77
112
  ## Rails Context
78
113
 
79
- The `railsContext` is a second param passed to your generator functions for React components. This is in addition to the props that are passed from the `react_component` Rails helper. For example:
114
+ The `railsContext` is a second param passed to your render-functions for React components. This is in addition to the props that are passed from the `react_component` Rails helper. For example:
80
115
 
81
116
  ERB view file:
82
117
 
@@ -91,7 +126,8 @@ This is what your HelloWorld.js file might contain. The railsContext is always a
91
126
  import React from 'react';
92
127
 
93
128
  export default (props, railsContext) => {
94
- return (
129
+ // Note, wrap in a function so this is React function component
130
+ return () => (
95
131
  <div>
96
132
  Your locale is {railsContext.i18nLocale}.<br/>
97
133
  Hello, {props.name}!
@@ -100,15 +136,17 @@ export default (props, railsContext) => {
100
136
  };
101
137
  ```
102
138
 
103
- ## Why is the railsContext is only passed to generator functions?
139
+ ## Why is the railsContext only passed to render-functions?
104
140
 
105
- There's no reason that the railsContext would ever get passed to your React component unless the value is explicitly put into the props used for rendering. If you create a react component, rather than a generator function, for use by React on Rails, then you get whatever props are passed in from the view helper, which **does not include the Rails Context**. It's trivial to wrap your component in a "generator function" to return a new component that takes both:
141
+ There's no reason that the railsContext would ever get passed to your React component unless the value is explicitly put into the props used for rendering. If you create a react component, rather than a render-function, for use by React on Rails, then you get whatever props are passed in from the view helper, which **does not include the Rails Context**. It's trivial to wrap your component in a "render-function" to return a new component that takes both:
106
142
 
107
143
  ```js
108
144
  import React from 'react';
109
145
  import AppComponent from './AppComponent';
110
146
  const AppComponentWithRailsContext = (props, railsContext) => (
111
- <AppComponent {...{...props, railsContext}}/>
147
+ // Create a React Function Component so you can
148
+ // use the React Hooks API in this React Function Component
149
+ () => <AppComponent {...{...props, railsContext}}/>
112
150
  )
113
151
  export default AppComponentWithRailsContext;
114
152
  ```
@@ -153,7 +191,7 @@ See [spec/dummy/config/initializers/react_on_rails.rb](https://github.com/shakac
153
191
  module RenderingExtension
154
192
 
155
193
  # Return a Hash that contains custom values from the view context that will get merged with
156
- # the standard rails_context values and passed to all calls to generator functions used by the
194
+ # the standard rails_context values and passed to all calls to render-functions used by the
157
195
  # react_component and redux_store view helpers
158
196
  def self.custom_context(view_context)
159
197
  {
@@ -5,6 +5,54 @@ If you would like help in migrating between React on Rails versions or help with
5
5
 
6
6
  We specialize in helping companies to quickly and efficiently move from versions before 9 to current. The older versions use the Rails asset pipeline to package client assets. The current and recommended way is to use Webpack 4 for asset preparation. You may also need help migrating from the `rails/webpacker`'s Webpack configuration to a better setup ready for Server Side Rendering.
7
7
 
8
+ ## Upgrading to v13
9
+ * Make sure that you are on a relatively more recent version of rails and webpacker.
10
+ * Updated API for ReactOnRails.register.
11
+
12
+ In order to solve the issues regarding React Hooks compatibility, the number of parameters
13
+ for functions is used to determine if you have a render function that will get invoked to
14
+ return a React component, or you are registering a React component defined by a function.
15
+
16
+ Registered Objects are of the following types:
17
+
18
+ ##### Correct
19
+ Either of these will work:
20
+ 1. Take **2 params** and return **a React function or class component**. A function component is a function
21
+ that takes zero or one params and returns a React Element, like JSX.
22
+ ```js
23
+ export default (props, _railsContext) => () => <Component {...props} />;
24
+ ```
25
+
26
+ 2. Take only zero or one params and you return a React Element, often JSX.
27
+ ```js
28
+ export default (props) => <Component {...props} />;
29
+ ```
30
+ ##### Broken, as this function takes two params and it returns a React Element from a JSX Literal
31
+ ```js
32
+ export default (props, _railsContext) => <Component {...props} />;
33
+ ```
34
+
35
+ If you make this mistake, you'll get this warning
36
+ `Warning: React.createElement: type is invalid -- expected a string (for built-in components) or a class/function (for composite components) but got: <Fragment />. Did you accidentally export a JSX literal instead of a component?`
37
+
38
+ And this error:
39
+ `react-dom.development.js:23965 Uncaught Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.`
40
+
41
+ In this example, you need to wrap the `<Component {...props} />` in a function call like this which
42
+ results in the return value being a React function component.
43
+
44
+ ```js
45
+ export default (props, _railsContext) => () => <Component {...props} />;
46
+ ```
47
+
48
+ If you have a pure component, taking one or zero parameters, and you have an unnecessary function
49
+ wrapper such that you're returning a function rather than a React Element, then:
50
+
51
+ 1. You won't see anything render.
52
+ 2. You will see this warning in development mode: `Warning: Functions are not valid as a React child. This may happen if you return a Component instead of <Component /> from render. Or maybe you meant to call this function rather than return it.`
53
+
54
+ ---------
55
+
8
56
  ## Upgrading rails/webpacker from v3 to v4
9
57
  ### Custom Webpack build file
10
58
  The default value for `extract_css` is **false** in `config/webpack.yml`. Custom webpack builds should set this value to true or else no CSS link tags are generated. You have a custom webpack build if you are not using [rails/webpacker](https://github.com/rails/webpacker to setup your Webpack configuration.
@@ -42,8 +90,8 @@ Reason for doing this: This enables your webpack bundles to bypass the Rails ass
42
90
  ##### ...while keeping your `client` directory
43
91
  * `.gitignore`: add `/public/webpack/*`
44
92
  * `Gemfile`: bump `react_on_rails` and add `webpacker`
45
- * layout views: anything bundled by webpack will need to be requested by a `javascript_pack_tag` or `stylesheet_pack_tag`.
46
- * Search your codebase for javascript_include_tag. Use the
93
+ * layout views: anything bundled by webpack will need to be requested by a `javascript_pack_tag` or `stylesheet_pack_tag`.
94
+ * Search your codebase for javascript_include_tag. Use the
47
95
  * `config/initializers/assets.rb`: we no longer need to modify `Rails.application.config.assets.paths` or append anything to `Rails.application.config.assets.precompile`.
48
96
  * `config/initializers/react_on_rails.rb`:
49
97
  * Delete `config.generated_assets_dir`. Webpacker's config now supplies this information