You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Note, the best way to understand how to use ReactOnRails is to study a few simple examples. You can do a quick demo setup, either on your existing app or on a new Rails app.
3
+
> **💡 Looking for the fastest way to get started?** Try our **[15-Minute Quick Start Guide](./quick-start/README.md)** instead.
4
4
5
-
This documentation assumes the usage of ReactOnRails with Shakapacker 7. For installation on Shakapacker 6, check [tips for usage with Shakapacker 6](./additional-details/tips-for-usage-with-sp6.md) first.
5
+
## Choose Your Starting Point
6
6
7
-
1. Do the quick [tutorial](./guides/tutorial.md).
8
-
2. Add React on Rails to an existing Rails app per [the instructions](./guides/installation-into-an-existing-rails-app.md).
9
-
3. Look at [spec/dummy](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy), a simple, no DB example.
10
-
4. Look at [github.com/shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial); it's a full-featured example live at [reactrails.com](https://reactrails.com).
7
+
The best way to understand React on Rails depends on your situation:
8
+
9
+
### 🚀 **New to React on Rails?**
10
+
11
+
**→ [15-Minute Quick Start](./quick-start/README.md)** - Get your first component working fast
12
+
13
+
### 📱 **Have an existing Rails app?**
14
+
15
+
**→ [Add to Existing App](./guides/installation-into-an-existing-rails-app.md)** - Integrate React on Rails
16
+
17
+
### 📚 **Want comprehensive tutorial?**
18
+
19
+
**→ [Complete Tutorial](./guides/tutorial.md)** - Step-by-step with Redux and routing
20
+
21
+
### 👀 **Learn by example?**
22
+
23
+
-**[Spec/Dummy](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy)** - Simple example in this repo
24
+
-**[Live Demo](https://reactrails.com)** with **[source code](https://github.com/shakacode/react-webpack-rails-tutorial)**
25
+
26
+
---
27
+
28
+
## System Requirements
29
+
30
+
✅ **Rails 7+** (Rails 5+ supported)
31
+
✅ **Ruby 3.0+** (Ruby 2.7+ supported)
32
+
✅ **Node.js 18+**
33
+
✅ **Shakapacker 7** (or Shakapacker 6 with [special setup](./additional-details/tips-for-usage-with-sp6.md))
34
+
35
+
> **Don't have Shakapacker?** It's the modern replacement for Webpacker and required for React on Rails.
11
36
12
37
## Basic Installation
13
38
@@ -16,11 +41,9 @@ You need a Rails application with Shakapacker installed and configured on it. Ch
16
41
```bash
17
42
rails new PROJECT_NAME --skip-javascript
18
43
cd PROJECT_NAME
19
-
bundle add shakapacker --strict
20
-
rails shakapacker:install
21
44
```
22
45
23
-
You may need to check [the instructions for installing into an existing Rails app](./guides/installation-into-an-existing-rails-app.md) if you have an already working Rails application.
46
+
## React on Rails Installation
24
47
25
48
1. Add the `react_on_rails` gem to Gemfile:
26
49
Please use [the latest version](https://rubygems.org/gems/react_on_rails) to ensure you get all the security patches and the best support.
@@ -31,40 +54,28 @@ You may need to check [the instructions for installing into an existing Rails ap
31
54
32
55
Commit this to git (or else you cannot run the generator in the next step unless you pass the option `--ignore-warnings`).
33
56
34
-
2. Run the install generator:
35
-
36
57
```bash
37
-
rails generate react_on_rails:install
58
+
git add -A
59
+
git commit -m "Initial commit"
38
60
```
39
61
40
-
3. Start the app:
41
-
42
-
- Run `./bin/dev` for HMR
43
-
- Run `./bin/dev static` for statically created bundles (no HMR)
44
-
45
-
4. Visit http://localhost:3000/hello_world.
46
-
47
-
### Turning on server rendering
48
-
49
-
With the code from running the React on Rails generator above:
62
+
2. Run the install generator:
50
63
51
-
1. Edit `app/views/hello_world/index.html.erb` and set the `prerender` option to `true`.
64
+
``bash
65
+
bundle exec rails generate react_on_rails:install
52
66
53
-
You may need to use `Node` as your js runtime environment by setting `EXECJS_RUNTIME=Node` into your environment variables.
67
+
```
54
68
55
-
2. Refresh the page.
69
+
```
56
70
57
-
Below is the line where you turn server rendering on by setting `prerender` to true:
- The `component_name`parameter is a string matching the name you used to expose your React component globally. So, in the above examples, if you had a React component named "HelloWorld", you would register it with the following lines:
101
+
`@component_name` is a string and corresponds to the name you used to globally expose your React component.
91
102
92
-
```js
93
-
importReactOnRailsfrom'react-on-rails';
94
-
importHelloWorldfrom'./HelloWorld';
95
-
ReactOnRails.register({ HelloWorld });
96
-
```
103
+
## Auto-Bundling (includes Auto-Registration)
97
104
98
-
Exposing your component in this way allows you to reference the component from a Rails view. You can expose as many components as you like, but their names must be unique. 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.
105
+
React on Rails supports **Auto-Bundling**, which automatically creates the webpack bundle _and_ registers your React components. This means you don’t have to manually configure packs or call `ReactOnRails.register(...)`.
99
106
100
-
-`@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:
With `auto_load_bundle: true`, and by placing your "exposed" components in the appropriate directories, React on Rails:
135
+
136
+
- Automatically finds and bundles your component.
137
+
- Automatically registers it for use.
138
+
- Eliminates the need for manual pack configuration.
139
+
140
+
See [Auto-Bundling: File-System-Based Automated Bundle Generation][./guides/auto-bundling-file-system-based-automated-bundle-generation.md]
141
+
142
+
Exposing your component in this way allows you to reference the component from a Rails view. You can expose as many components as you like, but their names must be unique. 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.
143
+
144
+
-`@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:
106
145
107
146
- 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://react.dev/reference/react/useContext). See [Render-Functions and the RailsContext](./guides/render-functions-and-railscontext.md) for more details on this topic.
108
147
@@ -120,22 +159,15 @@ issue.
120
159
};
121
160
```
122
161
123
-
See the [View Helpers API](./api/view-helpers-api.md) for more details on `react_component` and its sibling function `react_component_hash`.
124
-
125
-
## Globally Exposing Your React Components
162
+
## What Happens Next?
126
163
127
-
For the React on Rails view helper `react_component` to use your React components, you will have to **register** them in your JavaScript code.
164
+
The generator set up the following:
128
165
129
-
Use modules just as you would when using Webpack and React without Rails. The difference is that instead of mounting React components directly to an element using `React.render`, you **register your components to ReactOnRails and then mount them with helpers inside of your Rails views**.
2. Rails integration for rendering this component in a Rails view
168
+
3. Webpack configuration for building your JavaScript bundle
130
169
131
-
This is how to expose a component to the `react_component` view helper.
132
-
133
-
```javascript
134
-
// app/javascript/packs/hello-world-bundle.js
135
-
importHelloWorldfrom'../components/HelloWorld';
136
-
importReactOnRailsfrom'react-on-rails';
137
-
ReactOnRails.register({ HelloWorld });
138
-
```
170
+
139
171
140
172
#### Different Server-Side Rendering Code (and a Server-Specific Bundle)
141
173
@@ -145,7 +177,7 @@ Another way is to use a separate Webpack configuration file that can use a diffe
145
177
146
178
For details on techniques to use different code for client and server rendering, see: [How to use different versions of a file for client and server rendering](https://forum.shakacode.com/t/how-to-use-different-versions-of-a-file-for-client-and-server-rendering/1352). (_Requires creating a free account._)
147
179
148
-
## Specifying Your React Components: Register directly or use render-functions
180
+
## Specifying Your React Components
149
181
150
182
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 you to:
151
183
@@ -200,3 +232,24 @@ For details on using react_component_hash with react-helmet, see [our react-helm
200
232
201
233
React on Rails provides an option for automatic conversions of Rails `*.yml` locale files into `*.json` or `*.js`.
202
234
See the [How to add I18n](./guides/i18n.md) for a summary of adding I18n.
235
+
236
+
## More Reading
237
+
238
+
Depending on your goals, here's a progression of what to do next:
239
+
240
+
1.**[View Helpers API](./api/view-helpers-api.md)** - for more options of the `react_component` method.
241
+
2.**[Tutorial](./guides/tutorial.md)** - Comprehensive walkthrough of features with a real app.
242
+
3.**[Configuration](./guides/configuration.md)** - Details on every possible option you can configure.
243
+
4.**[Migration Guide](./guides/upgrading-react-on-rails.md)** - Upgrade advice for each version.
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
4
@@ -602,20 +602,6 @@ As of version 13.3.4, bundles inside directories that match `config.components_s
602
602
- **Minification**: Some code might break during minification - check console for errors
603
603
- **Environment**: Use `bin/dev prod` to test production-like assets locally
604
604
605
-
#### 8. Installation order issues
606
-
607
-
**Problem**: React on Rails installation fails or behaves unexpectedly.
608
-
609
-
**Solutions**:
610
-
611
-
- **Correct order**: Always install Shakapacker BEFORE React on Rails
612
-
```bash
613
-
bundle add shakapacker
614
-
rails shakapacker:install
615
-
bundle add react_on_rails
616
-
rails generate react_on_rails:install
617
-
```
618
-
- If you installed in wrong order, uninstall and reinstall in correct sequence
0 commit comments