Skip to content

Commit d8076e7

Browse files
ahangarhaahangarha
authored
Move docs to docs folder (#1312)
* Move docs to docs folder * Fix rubocop issues * Add placeholder for ToC * Fix url prefix to be usable on GitHub * Include sub headings for documentation in README
1 parent 7e369d6 commit d8076e7

12 files changed

+927
-856
lines changed

‎README.md

+38-854
Large diffs are not rendered by default.

‎docs/common-errors.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Common Errors
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
6+
- [Getting warning for `Can't resolve 'react-dom/client'` in React < 18](#getting-warning-for-cant-resolve-react-domclient-in-react--18)
7+
- [Undefined Set](#undefined-set)
8+
- [Using TheRubyRacer](#using-therubyracer)
9+
- [HMR](#hmr)
10+
11+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
12+
13+
## Getting warning for `Can't resolve 'react-dom/client'` in React < 18
14+
15+
You may see a warning like this when building a Webpack bundle using any version of React below 18. This warning can be safely [suppressed](https://webpack.js.org/configuration/other-options/#ignorewarnings) in your Webpack configuration. The following is an example of this suppression in `config/webpack/webpack.config.js`:
16+
17+
```diff
18+
- const { webpackConfig } = require('shakapacker')
19+
+ const { webpackConfig, merge } = require('shakapacker')
20+
21+
+const ignoreWarningsConfig = {
22+
+ ignoreWarnings: [/Module not found: Error: Can't resolve 'react-dom\/client'/],
23+
+};
24+
25+
- module.exports = webpackConfig
26+
+ module.exports = merge({}, webpackConfig, ignoreWarningsConfig)
27+
```
28+
29+
## Undefined Set
30+
```
31+
ExecJS::ProgramError (identifier 'Set' undefined):
32+
33+
(execjs):1
34+
```
35+
If you see any variation of this issue, see [Using TheRubyRacer](#using-therubyracer)
36+
37+
38+
## Using TheRubyRacer
39+
TheRubyRacer [hasn't updated LibV8](https://github.com/cowboyd/therubyracer/blob/master/therubyracer.gemspec#L20) (The library that powers Node.js) from v3 in 2 years, any new features are unlikely to work.
40+
41+
LibV8 itself is already [beyond version 7](https://github.com/cowboyd/libv8/releases/tag/v7.3.492.27.1) therefore many serverside issues are caused by old JS engines and fixed by using an up to date one such as [MiniRacer](https://github.com/discourse/mini_racer) or [TheRubyRhino](https://github.com/cowboyd/therubyrhino) on JRuby.
42+
43+
## HMR
44+
45+
Check out [Enabling Hot Module Replacement (HMR)](https://github.com/shakacode/shakapacker/blob/master/docs/react.md#enabling-hot-module-replacement-hmr) in Shakapacker documentation.
46+
47+
One caveat is that currently you [cannot Server-Side Render along with HMR](https://github.com/reactjs/react-rails/issues/925#issuecomment-415469572).

‎docs/component-generator.md

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Component Generator
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
6+
- [Use with JBuilder](#use-with-jbuilder)
7+
- [Camelize Props](#camelize-props)
8+
- [Changing Component Templates](#changing-component-templates)
9+
10+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
11+
12+
13+
You can generate a new component file with:
14+
15+
```sh
16+
rails g react:component ComponentName prop1:type prop2:type ... [options]
17+
```
18+
19+
For example,
20+
21+
```sh
22+
rails g react:component Post title:string published:bool published_by:instanceOf{Person}
23+
```
24+
25+
would generate:
26+
27+
```JSX
28+
var Post = createReactClass({
29+
propTypes: {
30+
title: PropTypes.string,
31+
published: PropTypes.bool,
32+
publishedBy: PropTypes.instanceOf(Person)
33+
},
34+
35+
render: function() {
36+
return (
37+
<React.Fragment>
38+
Title: {this.props.title}
39+
Published: {this.props.published}
40+
Published By: {this.props.publishedBy}
41+
</React.Fragment>
42+
);
43+
}
44+
});
45+
```
46+
47+
The generator also accepts options:
48+
49+
- `--es6`: generates a function component
50+
- `--coffee`: use CoffeeScript
51+
52+
For example,
53+
54+
```sh
55+
rails g react:component ButtonComponent title:string --es6
56+
```
57+
58+
would generate:
59+
60+
```jsx
61+
import React from "react"
62+
import PropTypes from "prop-types"
63+
64+
function ButtonComponent(props) {
65+
return (
66+
<React.Fragment>
67+
Title: {this.props.title}
68+
</React.Fragment>
69+
);
70+
}
71+
72+
ButtonComponent.propTypes = {
73+
title: PropTypes.string
74+
};
75+
76+
export default ButtonComponent
77+
```
78+
79+
**Note:** In a Shakapacker project, es6 template is the default template in the generator.
80+
81+
Accepted PropTypes are:
82+
83+
- Plain types: `any`, `array`, `bool`, `element`, `func`, `number`, `object`, `node`, `shape`, `string`
84+
- `instanceOf` takes an optional class name in the form of `instanceOf{className}`.
85+
- `oneOf` behaves like an enum, and takes an optional list of strings in the form of `'name:oneOf{one,two,three}'`.
86+
- `oneOfType` takes an optional list of react and custom types in the form of `'model:oneOfType{string,number,OtherType}'`.
87+
88+
Note that the arguments for `oneOf` and `oneOfType` must be enclosed in single quotes
89+
to prevent your terminal from expanding them into an argument list.
90+
91+
## Use with JBuilder
92+
93+
If you use Jbuilder to pass a JSON string to `react_component`, make sure your JSON is a stringified hash,
94+
not an array. This is not the Rails default -- you should add the root node yourself. For example:
95+
96+
```ruby
97+
# BAD: returns a stringified array
98+
json.array!(@messages) do |message|
99+
json.extract! message, :id, :name
100+
json.url message_url(message, format: :json)
101+
end
102+
103+
# GOOD: returns a stringified hash
104+
json.messages(@messages) do |message|
105+
json.extract! message, :id, :name
106+
json.url message_url(message, format: :json)
107+
end
108+
```
109+
110+
## Camelize Props
111+
112+
You can configure `camelize_props` option:
113+
114+
```ruby
115+
MyApp::Application.configure do
116+
config.react.camelize_props = true # default false
117+
end
118+
```
119+
120+
Now, Ruby hashes given to `react_component(...)` as props will have their keys transformed from _underscore_- to _camel_-case, for example:
121+
122+
```ruby
123+
{ all_todos: @todos, current_status: @status }
124+
# becomes:
125+
{ "allTodos" => @todos, "currentStatus" => @status }
126+
```
127+
128+
You can also specify this option in `react_component`:
129+
130+
```erb
131+
<%= react_component('HelloMessage', {name: 'John'}, {camelize_props: true}) %>
132+
```
133+
134+
## Changing Component Templates
135+
136+
To make simple changes to Component templates, copy the respective template file to your Rails project at `lib/templates/react/component/template_filename`.
137+
138+
For example, to change the [ES6 Component template](https://github.com/reactjs/react-rails/blob/master/lib/generators/templates/component.es6.jsx), copy it to `lib/templates/react/component/component.es6.jsx` and modify it.

‎docs/controller-actions.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Controller Actions
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
6+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
7+
8+
9+
Components can also be server-rendered directly from a controller action with the custom `component` renderer. For example:
10+
11+
```ruby
12+
class TodoController < ApplicationController
13+
def index
14+
@todos = Todo.all
15+
render component: 'TodoList', props: { todos: @todos }, tag: 'span', class: 'todo'
16+
end
17+
end
18+
```
19+
20+
You can also provide the "usual" `render` arguments: `content_type`, `layout`, `location` and `status`. By default, your current layout will be used and the component, rather than a view, will be rendered in place of `yield`. Custom data-* attributes can be passed like `data: {remote: true}`.
21+
22+
Prerendering is set to `true` by default, but can be turned off with `prerender: false`.

0 commit comments

Comments
 (0)