@@ -8,88 +8,153 @@ Full tutorial can be found at: [Fast Rich Client Rails Development With Webpack
88
99# Motivation
1010
11- 1 . Enable development of a JS client separate from Rails.
12- 2 . Enable easily retrofitting such a JS framework into an existing Rails app.
13- 3 . Enable the use of the JavaScript es6 transpiler.
14- 4 . Enable easily using npm modules with a Rails application.
11+ In no particular order:
12+ - Enable development of a JS client independently from Rails.
13+ - Easily enable use of npm modules with a Rails application.
14+ - Easily enable retrofitting such a JS framework into an existing Rails app.
15+ - Enable the use of the JavaScript ES6 transpiler.
1516
16- # Example of the following technologies:
17+ # Technologies involved
1718
18- 1 . react
19- 2 . react -bootstrap
20- 3 . webpack with hot-reload
21- 4 . es6-loader (es6 transpiler)
22- 5 . Simultaneously working with Rails 4.2
23- 6 . Deployable to Heroku
19+ 1 . React 0.11 (for front-end app)
20+ 2 . React -bootstrap 0.12
21+ 3 . Webpack with hot-reload 1.4 (for local dev)
22+ 4 . ES6 transpiler (es6-loader) 0.2
23+ 5 . Rails 4.2 (for backend app)
24+ 6 . Heroku (for deployment)
2425
25- # Running without Rails using Hot Reload
26+ # Javascript development without Rails using Hot Module Replacement (HMR)
2627
2728Setup node and run the node server.
29+
2830```
2931npm install
3032cd webpack && node server.js
3133```
3234
33- Point browser to [ http://0.0.0.0:3000 ] ( ) .
35+ Point your browser to [ http://0.0.0.0:3000 ] ( ) .
36+
3437
3538Save a change to a JSX file and see it update immediately in the browser! Note,
3639any browser state still exists, such as what you've typed in the comments box.
37- That's totally different than "Live Reload" which refreshes the browser.
40+ That's totally different than [ Live Reload] ( http://livereload.com/ ) which refreshes
41+ the browser.
42+
43+ # Rails integration
44+
45+ ## Build JS/CSS bundles
46+ Run this command to have webpack build the JS/CSS bundles and have them saved in the Rails
47+ asset pipeline (app/assets).
48+ The Webpack ExtractTextPlugin can optionally be used to extract the CSS out of
49+ the JS bundle. The following bundles would then be generated:
50+ - rails-bundle.js which gets saved to app/assets/javascripts
51+ - bootstrap-and-customizations.css which gets saved in app/assets/stylesheets
52+ Observe how the bundles are automatically re-generated whenever your JSX changes.
3853
39- # Rails
54+ ```
55+ cd webpack
56+ webpack -w --config webpack.rails.config.js
57+ ```
4058
59+ Make sure to invoke your local copy of the webpack executable as opposed
60+ to any globally installed webpack.
61+ See https://github.com/webpack/extract-text-webpack-plugin/blob/master/example/webpack.config.js
62+ If in doubt, run the following command:
4163```
64+ $(npm bin)/webpack -w --config webpack.rails.config.js
65+ ```
66+
67+ ## Run Rails server
68+
69+ Once the JS/CSS bundled have been generated into the Rails asset pipeline, you can start
70+ the Rails server.
71+
72+ ```
73+ cd <rails_project_name>
4274bundle install
4375rake db:setup
4476rails s -p 4000
4577```
46- Point browser to [ http://0.0.0.0:4000 ] ( ) .
78+ Point your browser to [ http://0.0.0.0:4000 ] ( ) .
4779
48- It's important to run the rails server on different port than the node server.
80+ It's important to run the Rails server on a different port than the node server.
4981
50- ## Automatically Building the rails-bundle.js
51- Run this command to automatically build the rails-bundle.js file in the
52- javascript directory whenever your jsx files change.
82+ # Webpack configuration
83+ - ` webpack.hot.config.js ` : Used by server.js to run the demo express server.
84+ - ` webpack.rails.config.js ` : Used to generate the Rails bundles.
85+ - ` webpack.common.config.js ` : Common configuration file to minimize code duplication.
5386
54- ```
55- cd webpack
56- webpack -w --config webpack.rails.config.js
57- ```
87+ # Bootstrap integration
88+ Notice that Bootstrap Sass is installed as both a gem and an npm package.
89+ When running the Rails app, the bootstrap-sass gem assets are loaded directly
90+ through the asset pipeline without passing through Webpack.
91+ See app/assets/application.css.scss.
92+ On the other hand when running the Webpack dev server, the bootrap-sass npm
93+ assets are loaded through Webpack (with help of the bootstrap-sass-loader).
94+ See webpack/webpack.hot.config.js.
95+
96+
97+ Bootstrap can be customized by hand-picking which modules to load and/or overwriting
98+ some of the Sass variables defined by the frameworks.
99+
100+ ## Bootstrap modules customization
101+
102+ If you are not using all the Bootstrap modules then you'll likely want to customize
103+ it to avoid loading unused assets. This customization is done in separate files
104+ for the Rails app versus the Webpack dev server so it's important to keep these
105+ in-sync as you develop your app in parallel using the Rails and the Webpack HMR
106+ environments.
107+
108+ - Rails Bootstrap customization file: app/assets/stylesheets/_ bootstrap-custom.scss
109+ - Webpack HMR Bootstrap customization file: webpack/bootstrap-sass.config.js
110+
111+ ## Bootstrap variables customization
58112
59- # Webpack Configuration
60- ` webpack.hot.config.js ` : Used by server.js to run the demo server.
61- ` webpack.rails.config.js ` : Used to generate the rails-bundle.js file
113+ If you need to customize some of the Sass variables defined in Bootstrap you
114+ can do so by overwriting these variables in a separate file and have it loaded
115+ before other Bootstrap modules.
62116
63- # Notes on Rails Assets
117+ To avoid duplicating this customization between Rails and Webpack HMR,
118+ this custom code has been consolidated under Webpack in
119+ webpack/assets/stylesheets/_ bootstrap-variables-customization.scss and the
120+ webpack/assets/stylesheets directory added to the Rails asset pipeline
121+ search path. See config config/application.rb. Keep that in mind as you
122+ customize the Bootstrap Sass variables.
123+
124+ # Notes on Rails assets
64125## Javascript
65- The ` webpack.rails.config.js ` file generates rails-bundle.js which is included
126+ The ` webpack.rails.config.js ` file generates rails-bundle.js which is then included
66127by the Rails asset pipeline.
67128
68129## Sass and images
69- 1 . The Webpack server loads the images from the ** symlink** of of the
130+ 1 . The Webpack server loads the images from the ** symlink** of the
70131 app/assets/images directory.
711322 . Since the images are not moved, Rails loads images via the normal asset
72133 pipeline features.
731343 . The ` image-url ` sass helper takes care of mapping the correct directories for
74135 images. The image directory for the webpack server is configured by this
75136 line:
76137
138+ ```
77139 { test: /\.scss$/, loader: "style!css!sass?outputStyle=expanded&imagePath=/assets/images"}
140+ ```
141+
142+ # Process management
143+ Run the following command in your development environment to invoke both Webpack and Rails.
144+ ```
145+ bundle exec foreman start -f Procfile.dev
146+ ```
78147
79148# Source Maps
80149They work for both Rails and the Webpack Server!
81150
82151# Deploying to Heroku
83152
84- In order to deploy to heroku, you'll need run this command once to set a custom
153+ In order to deploy to heroku, you'll need to run this command once to set a custom
85154buildpack:
86155
87156```
88157heroku config:add BUILDPACK_URL=https://github.com/ddollar/heroku-buildpack-multi.git
89158```
90159
91160This runs the two buildpacks in the ` .buildpacks ` directory.
92-
93- # TO DO
94- 1 . (Optionally) integrate twitter bootstrap assets into webpack build with way
95- to configure same options for Rails and Webpack.
0 commit comments