Mostly reasonable patterns for writing React on Rails
- Scope
- Organization
- Component Organization
- Formatting Props
- Patterns
- Computed Props
- Compound State
- prefer-ternary-to-sub-render
- View Components
- Container Components
- Anti-patterns
- Compound Conditions
- Cached State in render
- Existence Checking
- Setting State from Props
- Practices
- Naming Handle Methods
- Naming Events
- Using PropTypes
- Using Entities
- Gotchas
- Tables
- Add-ons
- ClassSet
- Other
- JSX
- ES6 Harmony
- react-rails
- rails-assets
- flux
This is how we write React.js on Rails. We've struggled to find the happy path. Recommendations here represent a good number of failed attempts. If something seems out of place, it probably is; let us know what you've found.
All examples written in ES2015 syntax now that the official react-rails gem ships with babel.
- class definition
- constructor
- event handlers
- 'component' lifecycle events
- getters
- render
- constructor
- defaultProps
- proptypes
class Person extends React.Component {
constructor (props) {
super(props);
this.state = { smiling: false };
this.handleClick = () => {
this.setState({smiling: !this.state.smiling});
};
}
componentWillMount () {
// add event listeners (Flux Store, WebSocket, document, etc.)
},
componentDidMount () {
// React.getDOMNode()
},
componentWillUnmount () {
// remove event listeners (Flux Store, WebSocket, document, etc.)
},
get smilingMessage () {
return (this.state.smiling) ? "is smiling" : "";
}
render () {
return (
<div onClick={this.handleClick}>
{this.props.name} {this.smilingMessage}
</div>
);
},
}
Person.defaultProps = {
name: 'Guest'
};
Person.propTypes = {
name: React.PropTypes.string
};
Wrap props on newlines for exactly 2 or more.
// bad
<Person
firstName="Michael" />
// good
<Person firstName="Michael" />
// bad
<Person firstName="Michael" lastName="Chan" occupation="Designer" favoriteFood="Drunken Noodles" />
// good
<Person
firstName="Michael"
lastName="Chan"
occupation="Designer"
favoriteFood="Drunken Noodles" />
Use getters to name computed properties.
// bad
firstAndLastName () {
return `${this.props.firstName} ${this.props.lastname}`;
}
// good
get fullName () {
return `${this.props.firstName} ${this.props.lastname}`;
}
See: Cached State in render anti-pattern
Prefix compound state getters with a verb for readability.
// bad
happyAndKnowsIt () {
return this.state.happy && this.state.knowsIt;
}
// good
get isHappyAndKnowsIt () {
return this.state.happy && this.state.knowsIt;
}
These methods MUST return a boolean
value.
See: Compound Conditions anti-pattern
Keep login inside the render
.
// bad
renderSmilingStatement () {
return <strong>{(this.state.isSmiling) ? " is smiling." : ""}</strong>;
},
render () {
return <div>{this.props.name}{this.renderSmilingStatement()}</div>;
}
// good
render () {
return (
<div>
{this.props.name}
{(this.state.smiling)
? <span>is smiling</span>
: null
}
</div>
);
}
Compose components into views. Don't create one-off components that merge layout and domain components.
// bad
class PeopleWrappedInBSRow extends React.Component {
render () {
return (
<div className="row">
<People people={this.state.people} />
</div>
);
}
}
// good
class BSRow extends React.Component {
render () {
return <div className="row">{this.props.children}</div>;
}
}
class SomeView extends React.createClass {
render () {
return (
<BSRow>
<People people={this.state.people} />
</BSRow>
);
}
}
A container does data fetching and then renders its corresponding sub-component. That's it. — Jason Bonta
// CommentList.js
class CommentList extends React.Component {
getInitialState () {
return { comments: [] };
}
componentDidMount () {
$.ajax({
url: "/my-comments.json",
dataType: 'json',
success: function(comments) {
this.setState({comments: comments});
}.bind(this)
});
}
render () {
return (
<ul>
{this.state.comments.map(({body, author}) => {
return <li>{body}—{author}</li>;
})}
</ul>
);
}
}
// CommentList.js
class CommentList extends React.Component {
render() {
return (
<ul>
{this.props.comments.map(({body, author}) => {
return <li>{body}—{author}</li>;
})}
</ul>
);
}
}
// CommentListContainer.js
class CommentListContainer extends React.Component {
getInitialState () {
return { comments: [] }
}
componentDidMount () {
$.ajax({
url: "/my-comments.json",
dataType: 'json',
success: function(comments) {
this.setState({comments: comments});
}.bind(this)
});
}
render () {
return <CommentList comments={this.state.comments} />;
}
}
Do not keep state in render
// bad
render () {
var name = `Mrs. ${this.props.name}`;
return <div>{name}</div>;
}
// good
render () {
return <div>{`Mrs. ${this.props.name}`}</div>;
}
// best
get fancyName () {
return `Mrs. ${this.props.name}`;
}
render () {
return <div>{this.fancyName}</div>;
}
This is mostly stylistic and keeps diffs nice. I doubt that there's a significant perf reason to do this.
See: Computed Props pattern
Don't put compound conditions in render
.
// bad
render () {
return <div>{if (this.state.happy && this.state.knowsIt) { return "Clapping hands" }</div>;
}
// better
get isTotesHappy() {
return this.state.happy && this.state.knowsIt;
},
render() {
return <div>{(this.isTotesHappy && "Clapping hands" }</div>;
}
The best solution for this would use a container component to manage state and pass new state down as props.
See: Compound State pattern
Do not check existence of prop
objects.
// bad
render() {
if (this.props.person) {
return <div>{this.props.person.firstName}</div>;
} else {
return null;
}
}
// good
getDefaultProps() {
return {
person: {
firstName: 'Guest'
}
};
},
render() {
return <div>{this.props.person.firstName}</div>;
}
This is only where objects or arrays are used. Use PropTypes.shape to clarify the types of nested data expected by the component.
Do not set state from props without obvious intent.
// bad
propTypes: {
items: React.PropTypes.array
},
getInitialState() {
return {
items: this.props.items
};
}
// good
propTypes: {
initialItems: React.PropTypes.array
},
getInitialState() {
return {
items: this.props.initialItems
};
}
Read: "Props in getInitialState Is an Anti-Pattern"
Name the handler methods after their triggering event.
// bad
punchABadger() {},
render() {
return <div onClick={this.punchABadger}> ... </div>;
}
// good
handleClick() {},
render() {
return <div onClick={this.handleClick}> ... </div>;
}
Handler names should:
- begin with
handle
- end with the name of the event they handle (eg,
Click
,Change
) - be present-tense
If you need to disambiguate handlers, add additional information between
handle
and the event name. For example, you can distinguish between onChange
handlers: handleNameChange
and handleAgeChange
. If you do this, ask
yourself if you should create another component class.
Use custom event names for components Parent-Child event listeners.
var Parent = React.createClass({
handleCry() {
// handle Child's cry
},
render() {
return (
<div className="Parent">
<Child onCry={this.handleCry} />
</div>
);
}
});
var Child = React.createClass({
render() {
return (
<div
className="Child"
onChange={this.props.onCry}>
...
</div>
);
}
});
Use PropTypes to communicate expectations and log meaningful warnings.
var MyValidatedComponent = React.createClass({
propTypes: {
name: React.PropTypes.string
},
...
});
This component will log a warning if it receives name
of a type other than string
.
<Person name=1337 />
// Warning: Invalid prop `name` of type `number` supplied to `MyValidatedComponent`, expected `string`.
Components may require props
var MyValidatedComponent = React.createClass({
propTypes: {
name: React.PropTypes.string.isRequired
},
...
});
This component will now validate the presence of name.
<Person />
// Warning: Required prop `name` was not specified in `Person`
Read: Prop Validation
Use React's String.fromCharCode()
for special characters.
// bad
<div>PiCO · Mascot</div>
// nope
<div>PiCO · Mascot</div>
// good
<div>{'PiCO ' + String.fromCharCode(183) + ' Mascot'}</div>
// better
<div>{`PiCO ${String.fromCharCode(183)} Mascot`}</div>
Read: JSX Gotchas
The browser thinks you're dumb. But React doesn't. Always use tbody
in your
table
components.
// bad
render() {
return (
<table>
<tr>...</tr>
</table>
);
}
// good
render() {
return (
<table>
<tbody>
<tr>...</tr>
</tbody>
</table>
);
}
The browser is going to insert tbody
if you forget. React will continue to
insert new tr
s into the table
and confuse the heck out of you. Always use
tbody
.
NOTE: the classSet addon has been deprecated. Use classNames instead on NPM and Bower.
Use classNames()
to manage conditional classes in your app:
// bad
render() {
var classes = ['MyComponent'];
if (this.state.active) {
classes.push('MyComponent--active');
}
return <div className={classes.join(' ')} />;
},
getClassName() {
var classes = ['MyComponent'];
if (this.state.active) {
classes.push('MyComponent--active');
}
return classes.join(' ');
}
// good
render() {
var classes = {
'MyComponent': true,
'MyComponent--active': this.state.active
};
<div className={classNames(classes)} />;
}
Read: Class Name Manipulation
We used to have some hardcore CoffeeScript lovers is the group. The unfortunate thing about writing templates in CoffeeScript is that it leaves you on the hook when certain implementations change that JSX would normally abstract.
We no longer recommend using CoffeeScript to write templates.
For posterity, you can read about how we used CoffeeScript for templates, when using CoffeeScript was non-negotiable: CoffeeScript and JSX.
These examples use the
harmony
option on react-rails
for ES6/ES2015 sugar. Examples use the createClass
API over React.Component
for consistency with the official documentation.
ES6 implementation in jstransform is limited.
react-rails should be used in all Rails apps that use React. It provides the perfect amount of glue between Rails conventions and React.
rails-assets should be considered for bundling js/css assets into your applications. The most popular React-libraries we use are registered on Bower and can be easily added through Bundler and react-assets.
caveats: rails-assets gives you access to bower projects via Sprockets requires. This is a win for the traditionally hand-wavy approach that Rails takes with JavaScript. This approach does buy you modularity or the ability to interop with JS tooling that requires modularity.
Use Alt for flux implementation. Alt is true to the flux pattern with the best documentation available.