react_on_rails 13.4.0 → 14.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (141) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +24 -2
  3. data/Gemfile.development_dependencies +10 -8
  4. data/README.md +2 -2
  5. data/lib/generators/react_on_rails/base_generator.rb +10 -2
  6. data/lib/generators/react_on_rails/dev_tests_generator.rb +1 -1
  7. data/lib/generators/react_on_rails/templates/base/base/config/shakapacker.yml +1 -1
  8. data/lib/generators/react_on_rails/templates/dev_tests/spec/rails_helper.rb +2 -2
  9. data/lib/generators/react_on_rails/templates/dev_tests/spec/system/hello_world_spec.rb +1 -1
  10. data/lib/react_on_rails/configuration.rb +39 -25
  11. data/lib/react_on_rails/git_utils.rb +3 -3
  12. data/lib/react_on_rails/helper.rb +2 -2
  13. data/lib/react_on_rails/json_output.rb +0 -17
  14. data/lib/react_on_rails/locales/base.rb +4 -4
  15. data/lib/react_on_rails/locales/to_js.rb +1 -1
  16. data/lib/react_on_rails/packs_generator.rb +2 -4
  17. data/lib/react_on_rails/react_component/render_options.rb +1 -1
  18. data/lib/react_on_rails/server_rendering_pool/ruby_embedded_java_script.rb +9 -9
  19. data/lib/react_on_rails/test_helper/webpack_assets_status_checker.rb +3 -3
  20. data/lib/react_on_rails/test_helper.rb +2 -2
  21. data/lib/react_on_rails/utils.rb +2 -8
  22. data/lib/react_on_rails/version.rb +1 -1
  23. data/lib/react_on_rails/version_checker.rb +2 -2
  24. data/lib/react_on_rails/webpacker_utils.rb +6 -0
  25. data/lib/tasks/assets.rake +1 -1
  26. data/react_on_rails.gemspec +4 -4
  27. metadata +4 -132
  28. data/.bookignore +0 -15
  29. data/.circleci/config.yml +0 -338
  30. data/.coveralls.yml +0 -1
  31. data/.dockerignore +0 -2
  32. data/.eslintignore +0 -17
  33. data/.eslintrc +0 -53
  34. data/.github/FUNDING.yml +0 -1
  35. data/.github/ISSUE_TEMPLATE/bug_report.md +0 -23
  36. data/.github/ISSUE_TEMPLATE/feature_request.md +0 -20
  37. data/.github/PULL_REQUEST_TEMPLATE.md +0 -19
  38. data/.github/workflows/lint-js-and-ruby.yml +0 -54
  39. data/.github/workflows/main.yml +0 -183
  40. data/.github/workflows/package-js-tests.yml +0 -35
  41. data/.github/workflows/rspec-package-specs.yml +0 -46
  42. data/.gitignore +0 -33
  43. data/.npmignore +0 -22
  44. data/.prettierignore +0 -14
  45. data/.prettierrc +0 -20
  46. data/.rspec +0 -2
  47. data/.rubocop.yml +0 -134
  48. data/.scss-lint.yml +0 -205
  49. data/.travis.yml +0 -61
  50. data/book.json +0 -18
  51. data/docs/additional-details/generator-details.md +0 -56
  52. data/docs/additional-details/manual-installation-overview.md +0 -30
  53. data/docs/additional-details/migrating-from-react-rails.md +0 -17
  54. data/docs/additional-details/recommended-project-structure.md +0 -69
  55. data/docs/additional-details/tips-for-usage-with-sp6.md +0 -15
  56. data/docs/additional-details/updating-dependencies.md +0 -31
  57. data/docs/additional-details/upgrade-webpacker-v3-to-v4.md +0 -10
  58. data/docs/api/javascript-api.md +0 -99
  59. data/docs/api/redux-store-api.md +0 -102
  60. data/docs/api/view-helpers-api.md +0 -133
  61. data/docs/contributor-info/errors-with-hooks.md +0 -45
  62. data/docs/contributor-info/generator-testing.md +0 -11
  63. data/docs/contributor-info/linters.md +0 -68
  64. data/docs/contributor-info/pull-requests.md +0 -42
  65. data/docs/contributor-info/releasing.md +0 -76
  66. data/docs/deployment/elastic-beanstalk.md +0 -63
  67. data/docs/deployment/heroku-deployment.md +0 -39
  68. data/docs/getting-started.md +0 -196
  69. data/docs/guides/client-vs-server-rendering.md +0 -27
  70. data/docs/guides/configuration.md +0 -289
  71. data/docs/guides/deployment.md +0 -5
  72. data/docs/guides/file-system-based-automated-bundle-generation.md +0 -197
  73. data/docs/guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md +0 -104
  74. data/docs/guides/how-react-on-rails-works.md +0 -44
  75. data/docs/guides/how-to-conditionally-server-render-based-on-device-type.md +0 -40
  76. data/docs/guides/how-to-use-different-files-for-client-and-server-rendering.md +0 -98
  77. data/docs/guides/i18n.md +0 -87
  78. data/docs/guides/installation-into-an-existing-rails-app.md +0 -66
  79. data/docs/guides/minitest-configuration.md +0 -31
  80. data/docs/guides/rails-webpacker-react-integration-options.md +0 -213
  81. data/docs/guides/react-on-rails-overview.md +0 -29
  82. data/docs/guides/react-server-rendering.md +0 -32
  83. data/docs/guides/render-functions-and-railscontext.md +0 -205
  84. data/docs/guides/rspec-configuration.md +0 -73
  85. data/docs/guides/tutorial.md +0 -371
  86. data/docs/guides/upgrading-react-on-rails.md +0 -304
  87. data/docs/guides/webpack-configuration.md +0 -42
  88. data/docs/home.md +0 -23
  89. data/docs/javascript/angular-js-integration-migration.md +0 -28
  90. data/docs/javascript/asset-pipeline.md +0 -12
  91. data/docs/javascript/capistrano-deployment.md +0 -18
  92. data/docs/javascript/code-splitting.md +0 -165
  93. data/docs/javascript/converting-from-custom-webpack-config-to-rails-webpacker-config.md +0 -10
  94. data/docs/javascript/credits.md +0 -10
  95. data/docs/javascript/foreman-issues.md +0 -15
  96. data/docs/javascript/images.md +0 -57
  97. data/docs/javascript/node-dependencies-and-npm.md +0 -19
  98. data/docs/javascript/react-and-redux.md +0 -36
  99. data/docs/javascript/react-helmet.md +0 -100
  100. data/docs/javascript/react-router.md +0 -90
  101. data/docs/javascript/server-rendering-tips.md +0 -55
  102. data/docs/javascript/troubleshooting-when-using-shakapacker.md +0 -77
  103. data/docs/javascript/troubleshooting-when-using-webpacker.md +0 -90
  104. data/docs/javascript/webpack-v1-notes.md +0 -23
  105. data/docs/javascript/webpack.md +0 -22
  106. data/docs/misc/articles.md +0 -20
  107. data/docs/misc/code_of_conduct.md +0 -13
  108. data/docs/misc/doctrine.md +0 -77
  109. data/docs/misc/style.md +0 -33
  110. data/docs/misc/tips.md +0 -10
  111. data/docs/outdated/deferred-rendering.md +0 -39
  112. data/docs/outdated/rails-assets-relative-paths.md +0 -195
  113. data/docs/outdated/rails-assets.md +0 -77
  114. data/docs/outdated/rails3.md +0 -9
  115. data/docs/rails/convert-rails-5-api-only-app.md +0 -19
  116. data/docs/rails/rails-engine-integration.md +0 -32
  117. data/docs/rails/rails_view_rendering_from_inline_javascript.md +0 -36
  118. data/docs/rails/turbolinks.md +0 -124
  119. data/docs/react-on-rails-pro/react-on-rails-pro.md +0 -43
  120. data/docs/testimonials/hvmn.md +0 -25
  121. data/docs/testimonials/resortpass.md +0 -13
  122. data/docs/testimonials/testimonials.md +0 -28
  123. data/jest.config.js +0 -4
  124. data/package-scripts.yml +0 -49
  125. data/package.json +0 -96
  126. data/rakelib/docker.rake +0 -26
  127. data/rakelib/dummy_apps.rake +0 -30
  128. data/rakelib/example_type.rb +0 -96
  129. data/rakelib/examples.rake +0 -64
  130. data/rakelib/examples_config.yml +0 -14
  131. data/rakelib/lint.rake +0 -30
  132. data/rakelib/node_package.rake +0 -15
  133. data/rakelib/release.rake +0 -92
  134. data/rakelib/run_rspec.rake +0 -103
  135. data/rakelib/task_helpers.rb +0 -62
  136. data/script/bootstrap +0 -33
  137. data/script/release +0 -3
  138. data/script/setup +0 -23
  139. data/script/test +0 -38
  140. data/webpackConfigLoader.js +0 -71
  141. data/yarn.lock +0 -7010
@@ -1,197 +0,0 @@
1
- # File-System-Based Automated Bundle Generation
2
-
3
- To use the automated bundle generation feature introduced in React on Rails v13.1.0, please upgrade to use [Shakapacker v6.5.1](https://github.com/shakacode/shakapacker/tree/v6.5.1) at least. If you are currently using Webpacker, please follow the migration steps available [v6 upgrade](https://github.com/shakacode/shakapacker/blob/master/docs/v6_upgrade.md). Then upgrade to Shakapacker 7 using [v7 upgrade](https://github.com/shakacode/shakapacker/blob/master/docs/v7_upgrade.md) guide.
4
-
5
- ## Configuration
6
-
7
- ### Enable nested_entries for Shakapacker
8
- To use the automated bundle generation feature, set `nested_entries: true` in the `shakapacker.yml` file like this.
9
- The generated files will go in a nested directory.
10
-
11
- ```yml
12
- default:
13
- ...
14
- nested_entries: true
15
- ```
16
-
17
- For more details, see [Configuration and Code](https://github.com/shakacode/shakapacker#configuration-and-code) section in [shakapacker](https://github.com/shakacode/shakapacker/).
18
-
19
- ### Configure Components Subdirectory
20
- `components_subdirectory` is the name of the matched directories containing components that will be automatically registered for use by the view helpers.
21
- For example, configure `config/initializers/react_on_rails` to set the name for `components_subdirectory`.·
22
-
23
- ```rb
24
- config.components_subdirectory = "ror_components"
25
- ```
26
-
27
- Now all React components inside the directories called `ror_components` will automatically be registered for usage with [`react_component`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component) and [`react_component_hash`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component_hash) helper methods provided by React on Rails.
28
-
29
- ### Configure `auto_load_bundle` Option
30
-
31
- For automated component registry, [`react_component`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component) and [`react_component_hash`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component_hash) view helper method tries to load generated bundle for component from the generated directory automatically per `auto_load_bundle` option. `auto_load_bundle` option in `config/initializers/react_on_rails` configures the default value that will be passed to component helpers. The default is `false`, and the parameter can be passed explicitly for each call.
32
-
33
- You can change the value in `config/initializers/react_on_rails` by updating it as follows:
34
-
35
- ```rb
36
- config.auto_load_bundle = true
37
- ```
38
-
39
- ### Update `.gitignore` file
40
- React on Rails automatically generates pack files for components to be registered in the `packs/generated` directory. To avoid committing generated files into the version control system, please update `.gitignore` to have
41
-
42
- ```gitignore
43
- # Generated React on Rails packs
44
- app/javascript/packs/generated
45
- ```
46
-
47
- *Note: the directory might be different depending on the `source_entry_path` in `config/shakapacker.yml`.*
48
-
49
- ## Usage
50
-
51
- ### Basic usage
52
-
53
- #### Background
54
- If the `shakapacker.yml` file is configured as instructed [here](https://github.com/shakacode/shakapacker#configuration-and-code), with the following configurations
55
-
56
- ```yml
57
- default: &default
58
- source_path: app/javascript
59
- source_entry_path: packs
60
- public_root_path: public
61
- public_output_path: packs
62
- nested_entries: true
63
- # And more
64
- ```
65
-
66
- the directory structure will look like this
67
-
68
- ```
69
- app/javascript:
70
- └── packs: # sets up webpack entries
71
- │ └── application.js # references FooComponentOne.jsx, BarComponentOne.jsx and BarComponentTwo.jsx in `../src`
72
- └── src: # any directory name is fine. Referenced files need to be under source_path
73
- │ └── Foo
74
- │ │ └── ...
75
- │ │ └── FooComponentOne.jsx
76
- │ └── Bar
77
- │ │ └── ...
78
- │ │ └── BarComponentOne.jsx
79
- │ │ └── BarComponentTwo.jsx
80
- └── stylesheets:
81
- │ └── my_styles.css
82
- └── images:
83
- └── logo.svg
84
- ```
85
-
86
- Previously, many applications would use one pack (webpack entrypoint) for many components. In this example, the`application.js` file manually registers server components, `FooComponentOne`, `BarComponentOne` and `BarComponentTwo`.
87
-
88
- ```jsx
89
- import ReactOnRails from 'react-on-rails';
90
- import FooComponentOne from '../src/Foo/FooComponentOne';
91
- import BarComponentOne from '../src/Foo/BarComponentOne';
92
- import BarComponentTwo from '../src/Foo/BarComponentTwo';
93
-
94
- ReactOnRails.register({ FooComponentOne, BarComponentOne, BarComponentTwo });
95
- ```
96
-
97
- Your layout would contain:
98
-
99
- ```erb
100
- <%= javascript_pack_tag 'application' %>
101
- <%= stylesheet_pack_tag 'application' %>
102
- ```
103
-
104
- Now suppose you want to use bundle splitting to minimize unnecessary javascript loaded on each page, you would put each of your components in the `packs` directory.
105
-
106
- ```
107
- app/javascript:
108
- └── packs: # sets up webpack entries
109
- │ └── FooComponentOne.jsx # Internally uses ReactOnRails.register
110
- │ └── BarComponentOne.jsx # Internally uses ReactOnRails.register
111
- │ └── BarComponentTwo.jsx # Internally uses ReactOnRails.register
112
- └── src: # any directory name is fine. Referenced files need to be under source_path
113
- │ └── Foo
114
- │ │ └── ...
115
- │ └── Bar
116
- │ │ └── ...
117
- └── stylesheets:
118
- │ └── my_styles.css
119
- └── images:
120
- └── logo.svg
121
- ```
122
-
123
- The tricky part is to figure out which bundles to load on any Rails view. [Shakapacker's `append_stylesheet_pack_tag` and `append_javascript_pack_tag` view helpers](https://github.com/shakacode/shakapacker#view-helper-append_javascript_pack_tag-and-append_stylesheet_pack_tag) enables Rails views to specify needed bundles for use by layout's call to `javascript_pack_tag` and `stylesheet_pack_tag`.
124
-
125
- #### Solution
126
-
127
- File-system-based automated pack generation simplifies this process with a new option for the view helpers.
128
-
129
- For example, if you wanted to utilize our file-system based entrypoint generation for `FooComponentOne` & `BarComponentOne`, but not `BarComponentTwo` (for whatever reason), then...
130
-
131
- 1. Remove generated entrypoints from parameters passed directly to `javascript_pack_tag` and `stylesheet_pack_tag`.
132
- 2. Remove generated entrypoints from parameters passed directly to `append_javascript_pack_tag` and `append_stylesheet_pack_tag`.
133
-
134
- Your layout would now contain:
135
-
136
- ```erb
137
- <%= javascript_pack_tag('BarComponentTwo') %>
138
- <%= stylesheet_pack_tag('BarComponentTwo') %>
139
- ```
140
-
141
- 3. Create a directory structure where the components that you want to be auto-generated are within `ReactOnRails.configuration.components_subdirectory`, which should be a subdirectory of `Shakapacker.config.source_path`:
142
-
143
- ```
144
- app/javascript:
145
- └── packs:
146
- │ └── BarComponentTwo.jsx # Internally uses ReactOnRails.register
147
- └── src:
148
- │ └── Foo
149
- │ │ └── ...
150
- │ │ └── ror_components # configured as `components_subdirectory`
151
- │ │ └── FooComponentOne.jsx
152
- │ └── Bar
153
- │ │ └── ...
154
- │ │ └── ror_components # configured as `components_subdirectory`
155
- │ │ │ └── BarComponentOne.jsx
156
- │ │ └── something_else
157
- │ │ │ └── BarComponentTwo.jsx
158
- ```
159
-
160
- 4. You no longer need to register the React components within the `ReactOnRails.configuration.components_subdirectory` nor directly add their bundles. For example you can have a Rails view using three components:
161
-
162
- ```erb
163
- <% append_javascript_pack('BarComponentTwo') %>
164
- <%= react_component("FooComponentOne", {}, auto_load_bundle: true) %>
165
- <%= react_component("BarComponentOne", {}, auto_load_bundle: true) %>
166
- <%= react_component("BarComponentTwo", {}) %>
167
- ```
168
-
169
- If a component uses multiple HTML strings for server rendering, the [`react_component_hash`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component_hash) view helper can be used on the Rails view, as illustrated below.
170
-
171
- ```erb
172
- <% foo_component_one_data = react_component_hash("FooComponentOne",
173
- prerender: true,
174
- auto_load_bundle: true
175
- props: {}
176
- ) %>
177
- <% content_for :title do %>
178
- <%= foo_component_one_data['title'] %>
179
- <% end %>
180
- <%= foo_component_one_data["componentHtml"] %>
181
- ```
182
-
183
- The default value of the `auto_load_bundle` parameter can be specified by setting `config.auto_load_bundle` in `config/initializers/react_on_rails.rb` and thus removed from each call to `react_component`.
184
-
185
- ### Server Rendering and Client Rendering Components
186
-
187
- If server rendering is enabled, the component will be registered for usage both in server and client rendering. In order to have separate definitions for client and server rendering, name the component files as `ComponentName.server.jsx` and `ComponentName.client.jsx`. The `ComponentName.server.jsx` file will be used for server rendering and the `ComponentName.client.jsx` file for client rendering. If you don't want the component rendered on the server, you should only have the `ComponentName.client.jsx` file.
188
-
189
- Once generated, all server entrypoints will be imported into a file named `[ReactOnRails.configuration.server_bundle_js_file]-generated.js`, which in turn will be imported into a source file named the same as `ReactOnRails.configuration.server_bundle_js_file`. If your server bundling logic is such that your server bundle source entrypoint is not named the same as your `ReactOnRails.configuration.server_bundle_js_file` & changing it would be difficult, please let us know.
190
-
191
- *Note: If specifying separate definitions for client and server rendering, please make sure to delete the generalized `ComponentName.jsx` file.*
192
-
193
- ### Using Automated Bundle Generation Feature with already defined packs
194
-
195
- As of version 13.3.4, bundles inside of directories that match `config.components_subdirectory` will be automatically added as entrypoints, while bundles outside of those directories will have to be manually added to the Shakapacker.config.source_entry_path or Webpack's `entry` rules.
196
-
197
-
@@ -1,104 +0,0 @@
1
- # HMR and Hot Reloading with the webpack-dev-server
2
-
3
- The `webpack-dev-server` provides:
4
-
5
- 1. Speedy compilation of client side assets
6
- 2. Optional HMR which means that the page will reload automatically when after
7
- compilation completes. Note, some developers do not like this, as you'll
8
- abruptly lose any tweaks within the Chrome development tools.
9
- 3. Optional hot-reloading. The older react-hot-loader has been deprecated in
10
- favor of [fast-refresh](https://reactnative.dev/docs/fast-refresh).
11
- For use with webpack, see **Client Side rendering and HMR using react-refresh-webpack-plugin** section bellow or visit [react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin) for additional details.
12
-
13
- If you are ***not*** using server-side rendering (***not*** using `prerender: true`),
14
- then you can follow all the regular docs for using the `bin/shakapacker-dev-server`
15
- during development.
16
-
17
- # Server Side Rendering with the Default shakacode/shakapacker bin/shakapacker-dev-server
18
-
19
- If you are using server-side rendering, then you have a couple options. The
20
- recommended technique is to have a different webpack configuration for server
21
- rendering.
22
-
23
- ## If you use the same Webpack setup for your server and client bundles
24
- If you do use the `webpack-dev-server` for prerendering, be sure to set the
25
- `config/initializers/react_on_rails.rb` setting of
26
-
27
- ```
28
- config.same_bundle_for_client_and_server = true
29
- ```
30
-
31
- `dev_server.hmr` maps to [devServer.hot](https://webpack.js.org/configuration/dev-server/#devserverhot).
32
- This must be false if you're using the webpack-dev-server for client and server bundles.
33
-
34
- `dev_server.inline` maps to [devServer.inline](https://webpack.js.org/configuration/dev-server/#devserverinline).
35
- This must also be false.
36
-
37
- If you don't configure these two to false, you'll see errors like:
38
-
39
- * `"ReferenceError: window is not defined" (if hmr is true)`
40
- * `"TypeError: Cannot read property 'prototype' of undefined" (if inline is true)`
41
-
42
- # Client Side rendering with HMR using react-refresh-webpack-plugin
43
- ## Basic installation
44
- To enable HMR functionality you have to use `./bin/shakapacker-dev-server`
45
- 1. In `config/shakapacker.yml` set **hmr** and **inline** `dev_server` properties to true.
46
- ```
47
- dev_server:
48
- https: false
49
- host: localhost
50
- port: 3035
51
- public: localhost:3035
52
- hmr: true
53
- # Inline should be set to true if using HMR
54
- inline: true
55
- ```
56
-
57
- 2. Add react refresh packages:
58
- ` yarn add @pmmmwh/react-refresh-webpack-plugin react-refresh -D`
59
-
60
- 3. HMR is for use with the `webpack-dev-server`, so we only add this for the `webpack-dev-server`.
61
- ```
62
- const { devServer } = require('shakapacker')
63
-
64
- const isWebpackDevServer = process.env.WEBPACK_DEV_SERVER
65
-
66
- //plugins
67
- if (isWebpackDevServer) {
68
- environment.plugins.append(
69
- 'ReactRefreshWebpackPlugin',
70
- new ReactRefreshWebpackPlugin({
71
- overlay: {
72
- sockPort: devServer.port
73
- }
74
- })
75
- )
76
- }
77
- ```
78
- We added overlay.sockedPort option in `ReactRefreshWebpackPlugin` to match the webpack dev-server port specified in `config/shakapacker.yml`. Thats way we make sockjs works properly and suppress error in browser console `GET http://localhost:[port]/sockjs-node/info?t=[xxxxxxxxxx] 404 (Not Found)`.
79
-
80
- 4. Add react-refresh plugin in `babel.config.js`
81
- ```
82
- module.export = function(api) {
83
- return {
84
- plugins: [process.env.WEBPACK_DEV_SERVER && 'react-refresh/babel'].filter(Boolean)
85
- }
86
- }
87
- ```
88
- That's it :).
89
- Now Browser should reflect .js along with .css changes without reloading.
90
-
91
- If by some reason plugin doesn't work you could revert changes and left only devServer hmr/inline to true affecting only css files.
92
-
93
- These plugins are working and tested with
94
- - babel 7
95
- - webpacker 5
96
- - bootstrap 4
97
- - jest 26
98
- - core-js 3
99
- - node 12.10.0
100
- - react-refresh-webpack-plugin@0.4.1
101
- - react-refresh 0.8.3
102
- - react_on_rails 11.1.4
103
-
104
- configuration.
@@ -1,44 +0,0 @@
1
- # How React on Rails Works (with Shakapcker)
2
-
3
- *Note, older versions of React on Rails pushed the Webpack bundles through the Asset Pipeline. This older method has *many* disadvantages, such as broken sourcemaps, performance issues, etc. If you need help migrating to the current way of bypassing the Asset Pipeline, [email Justin](mailto:justin@shakacode.com).*
4
-
5
- Webpack is used to generate JavaScript and CSS "bundles" directly to your `/public` directory. [Shakapacker](https://github.com/shakacode/shakapacker) provides view helpers to access the Webpack-generated (and fingerprinted) JS and CSS. These files totally skip the Rails asset pipeline. You are responsible for properly configuring your Webpack output. You will either use the standard Webpack configuration (*recommended*) or the `shakapacker` setup for Webpack.
6
-
7
- Ensure these generated bundle files are in your `.gitignore`, as you never want to add the large compiled bundles to git.
8
-
9
- Inside your Rails views, you can now use the `react_component` helper method provided by React on Rails. You can pass props directly to the react component helper.
10
-
11
- Optionally, you can also initialize a Redux store with the view or controller helper `redux_store` so that the redux store can be shared amongst multiple React components.
12
-
13
- ## Client-Side Rendering vs. Server-Side Rendering
14
-
15
- In most cases, you should use the `prerender: false` (default behavior) with the provided `react_component` 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`.
16
-
17
- 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. If you want to maximize the performance 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).
18
-
19
- ## HTML Source Code
20
-
21
- 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:
22
-
23
- 1. 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. 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.
24
- 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.
25
- 1. 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.
26
-
27
- You can see all this on the source for [reactrails.com](https://www.reactrails.com/)
28
-
29
- ## Building the Bundles
30
-
31
- 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 example Foreman `Procfile.dev` files 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. Alternatively, the `shakapacker` library also can ensure that your bundles are built.
32
-
33
- For example, you might create a [Procfile.dev](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/Procfile.dev).
34
-
35
- On production deployments that use asset precompilation, such as Heroku deployments, `shakapacker`, by default, will automatically run webpack to build your JavaScript bundles, running the command `bin/shakapacker` in your app.
36
-
37
- However, if you want to run a custom command to run webpack to build your bundles, then you will:
38
- 1. Define `config.build_production_command` in your [config/initializers/react_on_rails.rb](https://www.shakacode.com/react-on-rails/docs/guides/configuration/)
39
-
40
- Then React on Rails modifies the `assets:precompile` task to run your `build_production_command`.
41
-
42
- If you have used the provided generator, these bundles will automatically be added to your `.gitignore` to prevent extraneous noise from re-generated code in your pull requests. You will want to do this manually if you do not use the provided generator.
43
-
44
- You can stop React on Rails from modifying or creating the `assets:precompile` task, by setting a `REACT_ON_RAILS_PRECOMPILE` environment variable to `no`, `false`, `n` or `f`.
@@ -1,40 +0,0 @@
1
- # How to conditionally render server side based on the device type
2
-
3
- In general, we want to use CSS to do mobile responsive layouts.
4
-
5
- However, sometimes we want to have layouts sufficiently different that we can't do this via CSS. If we didn't do server rendering, we can check the device type on the client side. However, if we're doing server rendering, we need to send this data to the client code from the Rails server so that the server rendering can account for this.
6
-
7
- Here's an example:
8
-
9
- ## config/initializers/react_on_rails.rb
10
-
11
- ```ruby
12
- module RenderingExtension
13
- # Return a Hash that contains custom values from the view context that will get passed to
14
- # all calls to react_component and redux_store for rendering
15
- def self.custom_context(view_context)
16
- if view_context.controller.is_a?(ActionMailer::Base)
17
- {}
18
- else
19
- {
20
- desktop: !(view_context.browser.device.tablet? || view_context.browser.device.mobile?),
21
- tablet: view_context.browser.device.tablet?,
22
- mobile: view_context.browser.device.mobile? || false
23
- }
24
- end
25
- end
26
- end
27
-
28
- # Shown below are the defaults for configuration
29
- ReactOnRails.configure do |config|
30
- # See https://github.com/shakacode/react_on_rails/blob/master/docs/guides/configuration.md for the rest
31
-
32
- # This allows you to add additional values to the Rails Context. Implement one static method
33
- # called `custom_context(view_context)` and return a Hash.
34
- config.rendering_extension = RenderingExtension
35
- end
36
- ```
37
-
38
- Note, full details of the React on Rails configuration are [here in docs/basics/configuration.md](https://shakacode.com/react-on-rails/docs/guides/configuration/).
39
-
40
- See the doc file [docs/basics/generator-functions-and-railscontext.md](https://shakacode.com/react-on-rails/docs/guides/generator-functions-and-railscontext/#rails-context) for how your client-side code uses the device information
@@ -1,98 +0,0 @@
1
- ## How to use different versions of a file for client and server rendering
2
-
3
- There are 3 main ways to use different code for server vs. client rendering.
4
-
5
- ## A. Using different Entry Points
6
- Many projects will have different entry points for client and server rendering. This only works for a top-level entry point such as the entry point for a react-router app component.
7
-
8
- Your Client Entry can look like this:
9
-
10
- ```js
11
- import ReactOnRails from 'react-on-rails';
12
- import App from './ClientApp';
13
- ReactOnRails.register({ App })
14
- ```
15
-
16
- So your Server Entry can look like:
17
-
18
- ```js
19
- import ReactOnRails from 'react-on-rails';
20
- import App from './ServerApp';
21
- ReactOnRails.register({ App })
22
- ```
23
-
24
- Note that the only difference is on the second line of each of these examples.
25
-
26
- ## B. Two Options for Using Webpack Resolve Alias in the Webpack Config
27
- Per [Webpack Docs](https://webpack.js.org/configuration/resolve/#resolve-alias).
28
-
29
- ### 1. Update `webpack/set-resolve.js` to have a different resolution for the exact file:
30
-
31
- ```js
32
- function setResolve(builderConfig, webpackConfig) {
33
-
34
- // Use a different resolution for Client and Server file
35
- let SomeJsFile;
36
- if (builderConfig.serverRendering) {
37
- SomeJsFile = path.resolve(__dirname, "../bundles/SomeJsFileServer");
38
- } else {
39
- SomeJsFile = path.resolve(__dirname, "../bundles/SomeJsFileClient");
40
- }
41
-
42
- const resolve = {
43
- alias: {
44
- ... // blah blah
45
- SomeJsFile,
46
- ... // blah blah
47
- },
48
- ```
49
-
50
- Then you have this import:
51
-
52
- ```js
53
- import SomeJsFile from 'SomeJsFile';
54
- ```
55
-
56
- ### 2. Use a different resolution for the right directory of client or server files:
57
-
58
- #### a. Update `webpack/set-resolve.js` to have something like:
59
- ```js
60
- function setResolve(builderConfig, webpackConfig) {
61
-
62
- // Use a different resolution for Client and Server file
63
- let variant;
64
- if (builderConfig.serverRendering) {
65
- variant = path.resolve(__dirname, "../bundles/variant/ClientOnly");
66
- } else {
67
- variant = path.resolve(__dirname, "../bundles/variant/serverOnly");
68
- }
69
-
70
- const resolve = {
71
- alias: {
72
- ... // blah blah
73
- variant
74
- ... // blah blah
75
- },
76
- ```
77
-
78
- #### b. Add different versions of the file to the `bundles/variant/ClientOnly` and `bundles/variant/ServerOnly` directories
79
-
80
- #### c. Use the `variant` in import in a file that can be used both for client and server rendering:
81
-
82
- ```js
83
- import SomeJsFile from 'variant/SomeJsFile';
84
- import AnotherJsFile from 'variant/AnotherJsFile';
85
- ```
86
-
87
- ## C. Conditional code that can check if `window` is defined.
88
-
89
- This is probably the ugliest and hackiest way to do this, but it's quick! Essentially you wrap code that cannot execute server side in a conditional:
90
-
91
- ```js
92
- if (window) { // window should be falsy on the server side
93
- doSomethingClientOnly();
94
-
95
- // or do an import
96
- const foobar = require('foobar').default;
97
- }
98
- ```
data/docs/guides/i18n.md DELETED
@@ -1,87 +0,0 @@
1
- # Internationalization
2
-
3
- You can use [Rails internationalization (i18n)](https://guides.rubyonrails.org/i18n.html) in your client code.
4
-
5
- 1. Set `config.i18n_dir` in `config/initializers/react_on_rails.rb`:
6
-
7
- ```ruby
8
- # Replace the following line by the directory containing your translation.js and default.js files.
9
- config.i18n_dir = Rails.root.join("PATH_TO", "YOUR_JS_I18N_FOLDER")
10
- ```
11
-
12
- If you do not want to use the YAML files from `Rails.root.join("config", "locales")` and installed gems, you can also set `config.i18n_yml_dir`:
13
- ```ruby
14
- # Replace the following line by the location of your client i18n yml files
15
- # Without this option, all YAML files from Rails.root.join("config", "locales") and installed gems are loaded
16
- config.i18n_yml_dir = Rails.root.join("PATH_TO", "YOUR_YAML_I18N_FOLDER")
17
- ```
18
-
19
- 2. Add that directory (or just the generated files `translations.json` and `default.json`) to your `.gitignore`.
20
-
21
- 3. The locale files must be generated before `yarn build` using `rake react_on_rails:locale`.
22
-
23
- For development, you should adjust your startup scripts (`Procfile`s) so that they run `bundle exec rake react_on_rails:locale` before running any webpack watch process (`yarn run build:development`).
24
-
25
- If you are not using the React on Rails test helper,
26
- you may need to configure your CI to run `bundle exec rake react_on_rails:locale` before any webpack process as well.
27
-
28
- Note: if you try to lint before running tests, and you depend on the test helper to build your locales, linting will fail because the translations won't be built yet.
29
-
30
- The fix is either to
31
- 1) run the rake task to build the translations before running the lint command or
32
- 2) to run the tests first.
33
-
34
- By default, the locales are generated as JSON, but you can also generate them as JavaScript with [`react-intl`](https://formatjs.io/docs/getting-started/installation/) support:
35
-
36
- 1. Specify the i18n output format in `config/initializers/react_on_rails.rb`:
37
- ```rb
38
- config.i18n_output_format = "js"
39
- ```
40
-
41
- 2. Add `react-intl` & `intl` to `client/package.json`, and remember to `bundle install && yarn install`. The minimum supported versions are:
42
-
43
- ```js
44
- "dependencies": {
45
- ...
46
- "intl": "^1.2.5",
47
- "react-intl": "^2.1.5",
48
- ...
49
- }
50
- ```
51
-
52
- 3. In React, you need to initialize `react-intl`, and set its parameters:
53
-
54
- ```js
55
- ...
56
- import { addLocaleData } from 'react-intl';
57
- import en from 'react-intl/locale-data/en';
58
- import de from 'react-intl/locale-data/de';
59
- import { translations } from 'path_to/i18n/translations';
60
- import { defaultLocale } from 'path_to/i18n/default';
61
- ...
62
- // Initizalize all locales for react-intl.
63
- addLocaleData([...en, ...de]);
64
- ...
65
- // set locale and messages for IntlProvider.
66
- const locale = method_to_get_current_locale() || defaultLocale;
67
- const messages = translations[locale];
68
- ...
69
- return (
70
- <IntlProvider locale={locale} key={locale} messages={messages}>
71
- <CommentScreen {...{ actions, data }} />
72
- </IntlProvider>
73
- )
74
- ```
75
- ```js
76
- // In your component.
77
- import { defaultMessages } from 'path_to/i18n/default';
78
- ...
79
- return (
80
- { formatMessage(defaultMessages.yourLocaleKeyInCamelCase) }
81
- )
82
- ```
83
-
84
- # Notes
85
- * See why using JSON can perform better compared to JS for large amounts of data [https://v8.dev/blog/cost-of-javascript-2019#json](https://v8.dev/blog/cost-of-javascript-2019#json).
86
- * See [Support for Rails' i18n pluralization #1000](https://github.com/shakacode/react_on_rails/issues/1000) for a discussion of issues around pluralization.
87
- * *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.
@@ -1,66 +0,0 @@
1
- # Getting Started with an existing Rails app
2
-
3
- **Also consult the instructions for installing on a fresh Rails app**, see the [React on Rails Basic Tutorial](https://www.shakacode.com/react-on-rails/docs/guides/tutorial/).
4
-
5
- **If you have rails-5 API only project**, first [convert the rails-5 API only app to rails app](https://www.shakacode.com/react-on-rails/docs/rails/convert-rails-5-api-only-app-to-rails-app/).
6
-
7
- 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 `package.json` file.
8
-
9
- ```ruby
10
- gem "shakapacker", "7.0.1" # Use the latest and the exact version
11
- gem "react_on_rails", "13.3.1" # Use the latest and the exact version
12
- ```
13
-
14
- Or use `bundle add`:
15
-
16
- ```bash
17
- bundle add shakapacker --version=7.0.1 --strict
18
- bundle add react_on_rails --version=13.3.1 --strict
19
- ```
20
-
21
- 2. Run the following 2 commands to install Shakapacker 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).
22
-
23
- ```bash
24
- rails shakapacker:install
25
- ```
26
-
27
- 3. Commit this to git (or else you cannot run the generator unless you pass the option `--ignore-warnings`).
28
-
29
- 4. Run the generator with a simple "Hello World" example (more options below):
30
-
31
- ```bash
32
- rails generate react_on_rails:install
33
- ```
34
-
35
- For more information about this generator use `--help` option:
36
-
37
- ```bash
38
- rails generate react_on_rails:install --help
39
- ```
40
- 5. Ensure that you have `overmind` or `foreman` installed.
41
-
42
- Note: `foreman` should be installed on the system not on your project. [Read more](https://github.com/ddollar/foreman/wiki/Don't-Bundle-Foreman)
43
-
44
- 6. Start your Rails server:
45
-
46
- ```bash
47
- ./bin/dev
48
- ```
49
- Note: `foreman` defaults to PORT 5000 unless you set the value of PORT in your environment. For example, you can `export PORT=3000` to use the Rails default port of 3000. For the hello_world example, this is already set.
50
-
51
- 7. Visit [localhost:3000/hello_world](http://localhost:3000/hello_world).
52
-
53
- ## Installation
54
-
55
- See the [Installation Overview](https://www.shakacode.com/react-on-rails/docs/additional-details/manual-installation-overview/) for a concise set summary of what's in a React on Rails installation.
56
-
57
-
58
- ## NPM
59
-
60
- 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`):
61
-
62
- ```bash
63
- yarn add react-on-rails --exact
64
- ```
65
-
66
- 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.
@@ -1,31 +0,0 @@
1
- # Minitest Configuration
2
-
3
- The setup for minitest is the same as for rspec with the following difference.
4
-
5
- Rather than calling `ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)`, instead you will do something like this:
6
-
7
- ```ruby
8
- class ActiveSupport::TestCase
9
- setup do
10
- ReactOnRails::TestHelper.ensure_assets_compiled
11
- end
12
- end
13
- ```
14
-
15
-
16
- Or maybe something like this, from the [minitest docs](https://github.com/seattlerb/minitest/blob/master/lib/minitest/test.rb#L119):
17
-
18
- ```ruby
19
- module MyMinitestPlugin
20
- def before_setup
21
- super
22
- ReactOnRails::TestHelper.ensure_assets_compiled
23
- end
24
- end
25
-
26
- class MiniTest::Test
27
- include MyMinitestPlugin
28
- end
29
- ```
30
-
31
-