Fast Rich Client Rails Development With Webpack and the ES6 Transpiler

有更好的方式把 JavaScript 生态引入 Rails。

你有没有:

• 想知道是否有更好的方式在现有 Ruby on Rails 工程下使用现代 JavaScript 客户端框架？
• 烦恼怎样整合那些被打包成“模块”的 JavaScript 库和例子？
• 发现在全局命名空间下乱挂垃圾的弊端。
• 听说过 ES6 (又叫 Harmony)，下一代 JavaScript，现在正被那些硅谷大牛逼正在用得热火朝天(Facebook, Instagram, Square, 之类的)?

那你应该怎么在你的 Rails 工程中，实现以下这些呢：

• 你的 UI 原型，如果发现 JS 和 CSS/Sass 代码发生了变化，当保存的时候，立刻反应到界面，而无需重载页面。
• 成为 Node 生态中的一等公民，只需要在 package.json 指定依赖，然后执行 npm install，然后就可以在 JavaScript 文件里面很容易的就导入模块。
• 无缝集成基于 Node 的 JavaScript assets 到 Rails 的 Asset Pipeline，**无需规避** asset pipeline，而是让它共存，并能利用它。
• 无缝集成 node 客户端生态到现存的 Rails 工程中。
• 利用各种 JavaScript 工具，比如说 React JSX tranpiler 和 ES6 transpiler。

这篇文章将会告诉你如何在 Rails 开发过程中利用 Webpack 达成上面这些目标！

首先，我要给你讲个故事，告诉你我是怎么发现需要一个更好的方式将 JavaScript 生态集成到 Rails 中的。

手工拷贝粘贴一大堆 JavaScript 到 /vendor/assets/javascripts 有错？

想想如果你的 Ruby on Rails 工程没有 Bundler 会怎样？欧，屌炸了是不是！这就是手工拷贝 JavaScript 到 /vendor/assets/javascripts 的感觉！我实际上也挺担心的，因为越来越多 JavaScript 库开始依赖其他的 AMD (也叫 require.js) 或者 CommonJs 模块了。(有篇文章详细介绍了这种模块系统的工作方式，请看 Writing Modular JavaScript With AMD, CommonJS & ES Harmony。)对 Rails 社区来说，不得不面对的一个问题就是将流行的 JavaScript 库打包成 gems，比如说 jquery-rails gem。当然你可能觉得这样挺赞的，除非你发现你要用的 JavaScript 模块没有对应的 Gems。比如说，你想开始用 npm
packaged上那些很赞的 react 组件，比如说 react-bootstrap，或者你会想要用到 JavaScript 的工具鏈，比如说 JSX 和 ES6 transpilers (es6-transpiler 和 es6-module-transpiler)。

庆幸的是，我已经不是那个抱着 gemfiled 找 JavaScript 的小宝贝了！你现在就可以成为 JavaScript 的一等公民！

动机： React 和 ES6

我正式开始蹲 Node 的兔子洞是从准备开始用 React 框架开始的，包括它的 JSX transpiler。总的来说，React 库 看起来**独特，创新，令人印象深刻**。你可以简单的这样认为，客户端的 UI 就是一组组件，基于单向流数据进行渲染，从顶层组件到它的每个子组件。想要知道更多 React 的优点，看我的另外一篇文章 React on Rails Tutorial。而本文的目的在于，你可以这样认为，我要拿 React 来替换掉你最喜欢的富客户端框架。当然如果谁 fork 我的工程，然后建立一个用 EmberJS 的版本，我会很高兴的。

第一个任务用 React 看起来蛮简单的，因为这有 Ruby 的 Gem，ract-rails gem，它提供了一个真的蛮无痛的把 react 整合到 Rails 工程的方式。真的挺简单的。我做了一个例子，React on Rails Tutorial，还有相应的 github 仓库，justin808/react-rails-tutorial，这个例子告诉你怎样配合 Rails 4.2 scaffold generator 用 react-rails gem。然后我想把 react-bootstrap 用上去。这就没有 gem 了，我考虑过手工拷贝粘贴到我的 /vendor/assets/javascripts 目录，但是这让我觉得非常_不爽_，原因如下：

1. JavaScript 有一个成熟的依赖管理系统(packages 和模块 modules): npm (和 bower)。
2. 依赖通常还会依赖另外的包，不管在 Ruby 还是 JavaScript 的世界。想象一下如果 Ruby 依賴項要手动解决。
3. JavaScript 模块通常会依赖别的 CommonJs 或者 RequireJs 不错的模块。

(注： 对 Node 而言，module 是一个被打包的可以通过 require() 调用的 JavaScript 代码。更详细的信息，请查看 npm faq 以及 StackOverflow)

这有其他一些不错的方式来处理 Rails 应用的 assets: Five Ways to Manage Front-End Assets in Rails。我简单的尝试了一下这些技术，比如说加上使用 browserify-rails gem。但是，看起来都和 react-rails gem 冲突，而要是我不用这个 gem 的话，我就需要另寻出路去把 jsx 转化成 js 文件。这让我开始尝试使用 webpack module bundler。

Webpack

什么是 Webpack？

webpack 为模块和模块的依賴項生成静态 assets 的。

为什么我会尝试 Webpack？我推荐你看我的这篇Pete Hunt of the React team。这有些很充足的理由解释“为什么是 Webpack”：

1. 利用 npm (也可选 bower) 作为包管理。
2. 支持所有的模块语法，只要你喜欢就好。
3. 有许多 loaders (就像 pipeline)，包括 ES6 和 JSX。
4. Webpack Dev Server 对 JS 和 CSS/Sass 的快速原型开发很赞(Hot Module Replacement)。

开始学习 Webpack 的一个好去处是 Pete Hunt 的 webpack-howto。

我最初的时候想用 webpack module bundler 把 JS 从 Rails 分离出来，因为我想看到所谓的 react 代码可以“热重载”。你可以试试看这写简单的代码: react-tutorial-hot。Hot module Replacement会在运行时刷新 JS 代码(以及 CSS)而不需要任何的页面刷新。甚至是 JS 对象里面所有数据！这种技术比 Live Reload，要刷新整个页面要酷得多。

然后我就开始使用 Webpack 的这些功能了:

1. es6-loader，里面包括了 es6-transpiler 和 es6-module-transpiler。你要想玩一下，试试看 ES6 语法，可以通过 ES6 Fiddle。这里有个 great references on ES6 features。
2. jsx-loader，用 es6 来处理 jsx 文件的加载器。
3. 鸡零狗碎的整合，通过 npm 可以轻松的添加任何包，以及可以使用任何模块语法。

由于 Webpack 生成的 “bundle” 并不一定是被压缩过的，所以看起来应该可以被 Rails 的 asset pipeline 直接拿来用，果然，它可以！在这篇文章里面解释得很清楚：Setting Up Webpack with Rails 以及例子代码解释如何预编译 Webpack: Webpack In The Rails Asset Pipeline。

有了基础部分，我开始想要实现以下功能：

1. 可以用 Webpack Dev Server (的 hot module replacement) 来做客户端的 JS 原型开发，并且在我的 Rails 应用里面有同样的代码。这包括了 JavaScript， Sass， 和 Image 文件这些在 Rails 和 Webpack Dev Server 两边都有的通用文件。
2. 可以很容易的发布到 Heroku。

我的解決案放在了 github repo: justin808/react-webpack-rails-tutorial。这是基于我使用 react-rails gem 的例子: Rails 4.2, React, completed tutorial。接下来我会详细的解释一下这个工程。

安装

你需要安装 Node.js。我假设你已经有 Ruby 和 Rails 了。

1. Node.js: 你可以在这里找到 Node.js 的下载文件。嗯，我的一些朋友建议我直接用 Node.js 的安装包，而不是用 Brew。我还没试过 Brew。
2. 许多文章建议执行下面的命令，这样你就不需要在 node 命令行前用 sudo，所以，你自己更改你的 /usr/local 目录权限吧。

   $ sudo chown -R $USER /usr/local

3. 你的 /package.json 文件用来配置所有的依赖，然后你只要执行 npm install 就可以完全安装所有的包了。

一旦这些都开始工作了，这就像圣诞老人给我的应用带来一个完整的 Node 生态一样，爽呆了！

Bundler 和 Node Package Manager

所有的 Rails 开发者都熟悉 gems 和 Bundler(bundle)。对等的 Javascript 则是 package.json 文件和 Node Package Manager (npm) (请看下面的一节，我会说明为什么不选 Bower)。

这两个包管理系统都是通过检索值得信赖的在线资源来实现的。通过使用 package.json 文件远比手工下载依赖文件，然后拷贝到 /vendor/assets 目录要好得多！

为什么是 NPM 而不是 Bower？

许多流行的优秀的 JavaScript 在 Node Package Manager (npm) 和 Bower 上都有。因为要用 webpack，你应该会比较倾向用 npm，文档的理由如下：

许多情况下，npm 的模块质量要优于 bower。大多数情况下， Bower 只包括了 concatenated/bundled 文件，这样就会导致:

• webpack 更难管理
• webpack 更难优化
• 有时候还不能用到模块系统

所以爱上 CommonJs-风格模块吧，让 webpack 编译它。

Webpack 加上 Rails 的解決案说明

为了把整合 webpack 到 Rails，用了以下两种方式：

1. Webpack 被单独用到了 /webpack 目录，这样可以使用 Webpack Dev Server 来提供客户端 Javascript 原型快速开发工具。 webpack.hot.config.js 用来配置 Webpack Dev Server 用的 JS 和 CSS assets。
2. Webpack 监控并打包 /webpack/assets/javascripts 文件夹下面的所有 Javascript，生成 rails-bundle.js。文件 webpack.rails.config.js 转换 JSX 文件到 JS 文件，通过用 JSX 和 ES6 transpilers。

下面的这张图说明了在 Rails 中用 Webpack 的文件组织结构：

webpack.config

再次重申一下，我们之所以用 Webpack 是因为以下理由：

1. 为了能够使用 JS “模块”，包括使用 AMD(也叫 require.js) 或者 CommonJS 模块语法
2. 为了转换 JSX 文件(ES6 和 JSX 语法)为 JS 文件。注意，或者你并不需要把所有的 JS 文件都改成 ES6，因为很可能有些导进来的模块会发生冲突。

设置 webpack.config 文件，根据需求我们要有两个版本，Webpack Dev Server 和 Asset Pipeline。

修改 webpack.config

你也许会想要不要修改这个 webpack config 文件。那么下面有些你要注意的点。

1. module.exports.enty： 这个入口点会决定 webpack 将会把包放到哪里。虽然看起来很像 manifest 文件 /app/assets/javascripts/application.js，但是在这里你需要指定的仅仅是**entry**点。所以如果你指定了 ./assets/javascripts/example (你不需要文件后缀)作为入口点，那么你就不需要并且不要再指定 ./assets/javascripts/CommentBox 这样的作为入口点了。再次声明，这个依赖是为 Webpack 做的，而不是 Rails。

module.exports = {
 context: __dirname,
 entry: [
   "./assets/javascripts/example"
 ],

1. module.exports.externals: 如果你需要从 CDN 或者从 Rails gem 加载 jQuery，你应该像这样指定：

   module.exports.externals: {
     jquery: "var jQuery"
   },
   

2. module.exports.module.loaders: 这里是你可以用来暴露 Webpack 的 jQuery 给rails-bundle.js 的地方。这样那些 Rails 中非模块的 javascript 部分也也可以用上 jQuery 了。

module.exports.module: {
  loaders: [
    // Next 2 lines expose jQuery and $ to any JavaScript files loaded after rails-bundle.js
    //   in the Rails Asset Pipeline. Thus, load this one prior.
    { test: require.resolve("jquery"), loader: "expose?jQuery" },
    { test: require.resolve("jquery"), loader: "expose?$" }
  ]
}

Webpack Dev Server 和 Hot Module Replacement

因为等待 webpack 生成 rails-bundle.js 文件，然后刷新 Rails 页面是非常耗时的，和使用 Webpack Dev Server 以及 Hot Module Replacement 比起来简直就是渣渣，用后者如果可以，还能不修改客户端数据直接加载新的 JavaScript 和 Sass 代码。如果你觉得 Live Reload 很酷，那么你肯定会超爱这个功能。请看这段引用：

webpack-dev-server 是一个小型的 node.js express 服务，通过使用 webpack-dev-middleware 为 webpack 提供服务。它还有一个小型的运行时，通过 socket.io 链接到服务。服务推送状态变化到客户端，然后客户端响应这个变化。

它从当前目录来处理静态 assets 文件。如果文件没有找到引用当前 javascript 的一个 HTML 页面，那它会自动生成一个。

简而言之，文件 /webpack/server.js 是使用了 Webpack Dev Server API 的 http 服务：

1. /webpack/webpack.hot.config.js 配置 webpack 的 asset
2. 有多次 json 的响应
3. 设置 “hot” 为 true，这样就可以 hot module replacement 了。

JavaScripts

Webpack 处理文件夹 /webpack/assets/javascripts 的这些个方面的问题：

1. 为 Rails 或者 Webpack Dev Server 准备 JavaScript 文件“包”。包括执行 jsx 和 es6 loader，将 jsx 和 es6 语法转换成标准的 javascript。下面是相应的配置：

module.loaders = [{ test: /\.jsx$/, loaders: ["react-hot", "es6", "jsx?harmony"] }]

1. Webpack 同样处理你选择的模块加载语法(RequireJs, CommonJs, 或者 ES6)。

Sass 和图像

对于 Webpack Dev Serve(不是 Rails 版本的 rails-bundle.js)，Sass 通过 webpack 加载主要基于两个原因：

1. Webpack 能处理 sass 编译器。
2. 任何的 sass 或者 css 文件变化都可以通过 hot module loader 加载到浏览器。

文件 /webpack/scripts/webpack_only.jsx 包含下面：

require("test-stylesheet.css");
require("test-sass-stylesheet.scss");

这个 “require” 样式文件和 “require” JavaScript 一样。所以 /webpack/index.html 不会引用任何从 Sass 生成的东西。这个文件 webpack_only.jsx 也仅在 webpack.hot.config.js 文件里面作为一个“入口点”，也就是说它被明确的在 bundle 文件里面调用了。

Images 就有点搞了，在发布的时候，出于缓存目的，你希望你的图片能够加指纹(fingerprint)。对于那些使用新版本的 Rails 的用户来说，基本上就可以无视的，当然这要谢谢 Rails 的 asset pipeline 的这个功能。当然 webpack 也可以 fingerprint 图片，但是这个没必要，因为在我们的 Railse 发布环境中根本不需要用到 Webpack 的这个功能。所以我们只需要在 Webpack Dev Server 里面访问同样的图片就好。也就是，我们需要在 scss 文件中能够引用同一张图片，不管是 Webpack Dev Server 还是 Rails asset pipeline。

比如说，这里有一个 sass 代码的片段，用来加载 twitter_64.png 图片，在顶级目录 /app/assets/images 。这需要在 Rails 的 Asset Pipeline 和 Webpack Dev Serve 都能用。

.twitter-image {
  background-image: image-url(‘twitter_64.png‘);
}

问题是怎么从 Rails 和 Express 版本的服务端的样式文件里面拿到同一张图片，我们可以通过 symlink，而且 Git 存储方便。

1. /webpack/assets/image 指向 /app/assets/images 的文件夹
2. image-url sass helper 可以处理正确的图片目录映射关系。图片目录在 webpack 服务中通过下面这一行来配置：

module.loaders = [{ test: /.scss$/, loader: “style!css!sass?outputStyle=expanded&imagePath=/assets/images”}]

而 Rals 里面的 sass gem 则负责处理 Asset Pipline。

1. symlink 是必须的，因为 Webpack Dev Server 是不能从根目录上取到图片的。

以这种方式，图片在生产环境中就可以通过 Rails 的 Asset Pipeline 正确的被获取到，同时在 Webpack Dev Server 中也能很好的被使用。

Sourcemaps

当通过 Rails 应用调试 JavaScript 的时候，我不想在巨大的 rails-bundle.js 里面翻来翻去。Webpack 的 Sourcemap 能解决这个问题。首先我尝试用纯粹的 sourcemaps (分割文件，而不是集成)，不过因为一个错误导致失败了。然后，我又玩一些花招把文件移动到正确的地方，也就是 /public/assets。而且你要注意，在发布到 Heroku 过程中创建 sourcemap 文件会导致 Heroku 编译失败。所有这些动作都在文件 webpack.rails.config.js 的最底下处理。

在 Chrome 中， sourcemap 看起来大概像这样：

Heroku 发布

在 Heroku 上发布的时候，我们还需要做一些事情。

1. 如果在发布的时候安装 package.json 中的所有依赖是非常重的，所以只需要安装 dependencies 而_不是_ devDependencies。你**只需要**在本地 Webpack Dev Server 做开发的时候安装 devDependencies 的工具。
2. 清理你的编译缓存：

   heroku plugins:install https://github.com/heroku/heroku-repo.git
   heroku repo:purge_cache -a <my-app>
   

3. 在对 package.json 的 dependencies 做了**任何**变更之后，都要确保执行 npm-shrinkwrap
4. 我需要通过 Webpack 用文件 /lib/tasks/assets.rake 配置 compile_environment 任务来创建 rails-bundle.js 。
5. Heroku 需要 node 和 ruby 两种环境。为了发布到 Heroku，你需要执行下面这个命令来设置一个自定义 buildpack:

   heroku config:add BUILDPACK_URL=https://github.com/ddollar/heroku-buildpack-multi.git
   

   这会返回两个 buildpack 在文件 /.buildpacks 中，请查看 ddollar/heroku-buildpack-multi 了解更多细节。

为什么 node_modules 和 package.json 不放在 webpack 目录

当然把 node=modules 和 package.json 放到 /webpack 目录会更加整洁，但是问题是，因为用了自定义 buildpack，Heroku 会自己再安装一个 node_modules 出来。

为什么在 Webpack 下需要第二层 Assets 目录

起初，我确实是从 /app/assets/javascripts 目录下引用 JSX 文件的。但是我希望可以用 WebStorm 工程来管理 JavaScript 代码。我要么把 WebStorm 工程放到根目录，这样会把所有的 Ruby 目录都引进来，要么我用链接到 JavaScript 目录。你**绝对**不会想同时运行两个不同的 JetBrains 产品在同一个目录的，所以，就否决了我在 Rails 应用顶层用 WebStorm 的方案。用 Symlink 方式似乎可以达到目的，不过有时候会导致困惑，比如说有些时候我要用 Emacs 来打开 JSX。

把 webpack 打包文件放到 /webpack/assets 目录这种方式对我来说很管用。Webpack 打包这些文件，然后把生成的 rails-bundle.js 文件放到 /app/assets/javascripts 目录这看起来非常自然。

同样，我也把 Webpack 引用的样式文件都放到了 /webpack 目录。注意，我通过 Webpack 来加载样式文件，因为这样允许热加载样式文件到浏览器！如果你修改任何在 /webpack/assets/stylesheets 目录下的文件，你会看到几乎在你保存的同时，浏览器上就会反映出来变化。标准的 Rails 文件 /app/assets/stylesheets/application.css.scss 引用了 /webpack/assets/stylesheets 下面的式样文件。

如何添加 NPM(JavaScript) 模块依赖？

这有点像你用 Gemfile 来添加一个新的 gem 依赖。

1. 修改你的 /package.json 文件中 dependencies 节相应的行，添加你想要的包。你会希望指定版本，这是 Node 社区强烈建议的。你只要 Google 一下 “npm <啥模块>” 然后你会得到这个 npm 包的页面链接，然后你去看看你要的版本。比如说你想添加一个 marked 依赖，我在 package.json 里面加上这行：

“marked”: “^0.3.2”,

1. 插入模块引用。比如，导入 marked 包：

   var marked = require("marked");
   

   如何升级 Node 依赖

你准备要升级你的包的时候，你应该会用到下面这一步。导入 npm-check-updates 和 npm-shrinkwrap.

cd <top level of your app>
rm -rf node_modules
npm install -g npm-check-updates
npm-check-updates -u
npm install
npm-shrinkwrap

快速客户端开发

恭喜!你已经知道了我认为可以进行快速开发的 JavaScript 开发的秘密武器了。一旦你安装好，上面的每个步骤，那么像下面这样：

1. 运行 Webpack Dev Server 在 3000 端口

   cd webpack && node server.js
   

2. 在浏览器中访问 http://0.0.0.0:3000
3. 打开另外一个 shell 然后执行

   foreman start -f Procfile.dev
   

4. 在浏览器打开 http://0.0.0.0:4000 来看看你是否能看到 rails-bundle.js 文件。
5. 更新 /webpack/assets 下面的 jsx 和 scss 文件，然后看看 3000 端口上的浏览器所发生的变化。
6. 创建 JSX 再带些静态的数据，然后再试试看从 server.js 把 JSON 发送到客户端。
7. 一旦这些都能运作起来，尝试从 Rails 服务创建 JSON。
8. 发布到 Heroku！
9. 搞定！

链接

1. 本文的 Github 仓库：justin808/react-webpack-rails-tutorial
2. Heroku 上可用版本：http://react-webpack-rails-tutorial.herokuapp.com/
3. Storing or Excluding Node Modules in Rails Git Repositories
4. Pete Hunt 的 introductory guide to getting started with Webpack。