README.md in react-rails-2.4.7 vs README.md in react-rails-2.5.0

- old
+ new

@@ -1,21 +1,20 @@ # React-Rails [![Gem](https://img.shields.io/gem/v/react-rails.svg?style=flat-square)](http://rubygems.org/gems/react-rails) [![npm](https://img.shields.io/npm/v/react_ujs.svg?style=flat-square)](https://www.npmjs.com/package/react_ujs) [![Build Status](https://img.shields.io/travis/reactjs/react-rails/master.svg?style=flat-square)](https://travis-ci.org/reactjs/react-rails) -[![Gemnasium](https://img.shields.io/gemnasium/reactjs/react-rails.svg?style=flat-square)](https://gemnasium.com/reactjs/react-rails) -[![Code Climate](https://img.shields.io/codeclimate/github/reactjs/react-rails.svg?style=flat-square)](https://codeclimate.com/github/reactjs/react-rails) +[![Maintainers Wanted](https://img.shields.io/badge/Maintainers-Wanted-red.svg) -React-Rails is a flexible tool to use [React](http://facebook.github.io/react/) with Rails. It: +React-Rails is a flexible tool to use [React](http://facebook.github.io/react/) with Rails. The benefits: * Automatically renders React server-side and client-side * Supports Webpacker 3.x, 2.x, 1.1+ * Supports Sprockets 4.x, 3.x, 2.x * Lets you use [JSX](http://facebook.github.io/react/docs/jsx-in-depth.html), [ES6](http://es6-features.org/), [TypeScript](https://www.typescriptlang.org/), [CoffeeScript](http://coffeescript.org/) -Example app code available here: https://github.com/BookOfGreg/react-rails-example-app +A source code example utilizing React-Rails: https://github.com/BookOfGreg/react-rails-example-app <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> ## Contents @@ -38,69 +37,86 @@ - [Component Generator](#component-generator) - [Use with JBuilder](#use-with-jbuilder) - [Camelize Props](#camelize-props) - [Upgrading](#upgrading) - [2.3 to 2.4](#23-to-24) +- [Common Errors](#common-errors) - [Related Projects](#related-projects) - [Contributing](#contributing) <!-- END doctoc generated TOC please keep comment here to allow auto update --> -The React-Rails Wiki has lots of additional information about React-Rails including many "how-to" articles and answers to the most frequently asked questions. Please browse the Wiki after finishing this README: - +After reading this README file, additional information about React-Rails can be found in the Wiki page: https://github.com/reactjs/React-Rails/wiki +The Wiki page features a significant amount of additional information about React-Rails which includes instructional articles and answers to the most frequently asked questions. ## Get started with Webpacker -[or Get started with Sprockets](#use-with-asset-pipeline) +[Alternatively, get started with Sprockets](#use-with-asset-pipeline) -[Webpacker](https://github.com/rails/webpacker) integrates modern JS tooling with Rails. +[Webpacker](https://github.com/rails/webpacker) provides modern JS tooling for Rails. Here are the listed steps for integrating Webpacker and Rails-React with Rails: -Add `webpacker` and `react-rails` to your gemfile and run the installers: +##### 1) Create a new Rails app: +``` +$ rails new my-app +$ cd my-app +``` +##### 2) Add `webpacker` and `react-rails` to your gemfile: ``` +gem 'webpacker' +gem 'react-rails' +``` + +##### 3) Now run the installers: +``` $ bundle install $ rails webpacker:install # OR (on rails version < 5.0) rake webpacker:install $ rails webpacker:install:react # OR (on rails version < 5.0) rake webpacker:install:react $ rails generate react:install ``` - This gives you: - `app/javascript/components/` directory for your React components - [`ReactRailsUJS`](#ujs) setup in `app/javascript/packs/application.js` - `app/javascript/packs/server_rendering.js` for [server-side rendering](#server-side-rendering) -Link the JavaScript pack in Rails view using `javascript_pack_tag` [helper](https://github.com/rails/webpacker#usage), for example: - +##### 4) Link the JavaScript pack in Rails view using `javascript_pack_tag` [helper](https://github.com/rails/webpacker#usage): ``` -<!-- application.html.erb --> +<!-- application.html.erb in Head tag below turbolinks --> <%= javascript_pack_tag 'application' %> ``` -Generate your first component: - +##### 5) Generate your first component: ``` $ rails g react:component HelloWorld greeting:string ``` -Your component is added to `app/javascript/components/` by default. - -You can also generate your component in a subdirectory: - +##### 6) You can also generate your component in a subdirectory: ``` $ rails g react:component my_subdirectory/HelloWorld greeting:string ``` +Note: Your component is added to `app/javascript/components/` by default. -[Render it in a Rails view](#view-helper): -```erb -<%= react_component("HelloWorld", { greeting: "Hello" }) %> +##### 7) [Render it in a Rails view](#view-helper): + ``` +<!-- erb: paste this in view --> +<%= react_component("HelloWorld", { greeting: "Hello from react-rails." }) %> +``` +##### 8) Lets Start the app: +``` +$ rails s +``` +output: greeting: Hello from react-rails", inspect webpage in your browser too see change in tag props. + +### Component name + The component name tells `react-rails` where to load the component. For example: `react_component` call | component `require` -----|----- `react_component("Item")` | `require("Item")` @@ -141,15 +157,50 @@ $ yarn add @types/react @types/react-dom ``` Doing this will allow React-Rails to support the .tsx extension. +### Test component + +You can use `assert_react_component` to test component render: + +app/views/welcome/index.html.erb + +```erb +<%= react_component("HelloWorld", { greeting: "Hello from react-rails.", info: { name: "react-rails" } }, { class: "hello-world" }) %> +``` + +```rb +class WelcomeControllerTest < ActionDispatch::IntegrationTest + test 'assert_react_component' do + get "/welcome" + assert_equal 200, response.status + + # assert rendered react component and check the props + assert_react_component "HelloWorld" do |props| + assert_equal "Hello from react-rails.", props[:greeting] + assert_equal "react-rails", props[:info][:name] + assert_select "[class=?]", "hello-world" + end + + # or just assert component rendered + assert_react_component "HelloWorld" + end +end +``` + ## Use with Asset Pipeline -`react-rails` provides a pre-bundled React.js & a UJS driver to the Rails asset pipeline. Get started by installing: +`react-rails` provides a pre-bundled React.js & a UJS driver to the Rails asset pipeline. Get started by adding the `react-rails` gem: ``` +gem 'react-rails' +``` + +And then install the react generator: + +``` $ rails g react:install ``` Then restart your development server. @@ -198,10 +249,22 @@ - `#initialize(options)`, where options is the value passed to `config.react.jsx_transform_options` - `#transform(code_string)` to return a string of transformed code `react-rails` provides two transformers, `React::JSX::BabelTransformer` (which uses [ruby-babel-transpiler](https://github.com/babel/ruby-babel-transpiler)) and `React::JSX::JSXTransformer` (which uses the deprecated `JSXTransformer.js`). +#### Transform Plugin Options + +To supply additional transform plugins to your JSX Transformer, assign them to `config.react.jsx_transform_options` + +`react-rails` uses the Babel version of the `babel-source` gem. + +For example, to use `babel-plugin-transform-class-properties` : + + config.react.jsx_transform_options = { + optional: ['es7.classProperties'] + } + ### React.js versions `//= require react` brings `React` into your project. By default, React's [development version] is provided to `Rails.env.development`. You can override the React build with a config: @@ -326,11 +389,11 @@ ### `getConstructor` Components are loaded with `ReactRailsUJS.getConstructor(className)`. This function has two built-in implementations: - On the asset pipeline, it looks up `className` in the global namespace. -- On Webpacker, it `require`s files and accesses named exports, as described in [Use with Webpacker](#use-with-webpacker). +- On Webpacker, it `require`s files and accesses named exports, as described in [Get started with Webpacker](#get-started-with-webpacker). You can override this function to customize the mapping of name-to-constructor. [Server-side rendering](#server-side-rendering) also uses this function. ## Server-Side Rendering @@ -560,9 +623,34 @@ For the vast majority of cases this will get you most of the migration: - global find+replace `React.Prop` -> `Prop` - add `import PropTypes from 'prop-types'` (Webpacker only) - re-run `bundle exec rails webpacker:install:react` to update npm packages (Webpacker only) + +## Common Errors +1) While using installers.(rails webpacker:install:react && rails webpacker:install) +Error: +``` +public/packs/manifest.json. Possible causes: +1. You want to set webpacker.yml value of compile to true for your environment + unless you are using the `webpack -w` or the webpack-dev-server. +2. webpack has not yet re-run to reflect updates. +3. You have misconfigured Webpacker's config/webpacker.yml file. +4. Your webpack configuration is not creating a manifest. +or +yarn: error: no such option: --dev +ERROR: [Errno 2] No such file or directory: 'add' +``` +Fix: Try updating yarn package. +``` +sudo apt remove cmdtest +sudo apt remove yarn +curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +sudo apt-get update && sudo apt-get install yarn + +yarn install +``` ## Related Projects - [webpacker-react](https://github.com/renchap/webpacker-react): Integration of React with Rails utilizing Webpack with Hot Module Replacement (HMR). - [The Free React on Rails Course](https://learnetto.com/users/hrishio/courses/the-free-react-on-rails-5-course) A free video course which teaches the basics of React and how to get started using it in Rails with `react-rails`.