@rails/webpacker
Advanced tools
Readme
Webpacker makes it easy to use the JavaScript pre-processor and bundler Webpack 3.x.x+ to manage application-like JavaScript in Rails. It coexists with the asset pipeline, as the primary purpose for Webpack is app-like JavaScript, not images, CSS, or even JavaScript Sprinkles (that all continues to live in app/assets).
However, it is possible to use Webpacker for CSS, images and fonts assets as well, in which case you may not even need the asset pipeline. This is mostly relevant when exclusively using component-based JavaScript frameworks.
You can either add Webpacker during setup of a new Rails 5.1+ application
using new --webpack option:
# Available Rails 5.1+
rails new myapp --webpack
Or add it to your Gemfile, run bundle and ./bin/rails webpacker:install or
bundle exec rake webpacker:install (on rails version < 5.0):
# Gemfile
gem 'webpacker', '~> 2.0'
# OR if you prefer to use master
gem 'webpacker', git: 'https://github.com/rails/webpacker.git'
Note: Use rake instead of rails if you are using webpacker
with rails version < 5.0
Webpacker ships with basic out-of-the-box integration for React, Angular, Vue and Elm. You can see a list of available commands/tasks by running:
# Within rails app
./bin/rails webpacker
or in rails version < 5.0
# Within rails app
./bin/rake webpacker
To use Webpacker with React, create a
new Rails 5.1+ app using --webpack=react option:
# Rails 5.1+
rails new myapp --webpack=react
(or run ./bin/rails webpacker:install:react in a existing Rails app already
setup with webpacker).
The installer will add all relevant dependencies using yarn, any changes
to the configuration files and an example React component to your
project in app/javascript/packs so that you can experiment with React right away.
To use Webpacker with Angular, create a
new Rails 5.1+ app using --webpack=angular option:
# Rails 5.1+
rails new myapp --webpack=angular
(or run ./bin/rails webpacker:install:angular on a Rails app already
setup with webpacker).
The installer will add TypeScript and Angular core libraries using yarn plus
any changes to the configuration files. An example component is written in
TypeScript will also be added to your project in app/javascript so that
you can experiment with Angular right away.
To use Webpacker with Vue, create a
new Rails 5.1+ app using --webpack=vue option:
# Rails 5.1+
rails new myapp --webpack=vue
(or run ./bin/rails webpacker:install:vue on a Rails app already setup with webpacker).
The installer will add Vue and required libraries using yarn plus
any changes to the configuration files. An example component will
also be added to your project in app/javascript so that you can
experiment Vue right away.
To use Webpacker with Elm, create a
new Rails 5.1+ app using --webpack=elm option:
# Rails 5.1+
rails new myapp --webpack=elm
(or run ./bin/rails webpacker:install:elm on a Rails app already setup with webpacker).
The Elm library and core packages will be added via Yarn and Elm itself.
An example Main.elm app will also be added to your project in app/javascript
so that you can experiment with Elm right away.
Webpacker ships with two binstubs: ./bin/webpack and ./bin/webpack-dev-server.
Both are thin wrappers around the standard webpack.js and webpack-dev-server.js
executable to ensure that the right configuration file and environment variables
are loaded depending on your environment.
In development, Webpacker compiles on demand rather than upfront by default. This happens when you refer to any of the pack assets using the Webpacker helper methods. That means you don't have to run any separate process. Compilation errors are logged to the standard Rails log.
If you want to use live code reloading, or you have enough JavaScript that on-demand compilation is too slow, you'll need to run ./bin/webpack-dev-server
in a separate terminal from ./bin/rails server. This process will watch for changes
in the app/javascript/packs/*.js files and automatically reload the browser to match.
Once you start this development server, Webpacker will automatically start proxying all webpack asset requests to this server. When you stop the server, it'll revert to on-demand compilation again.
You can also pass CLI options supported by webpack-dev-server. Please note that inline options will always take precedence over the ones already set in the configuration file.
./bin/webpack-dev-server --host example.com --inline true --hot false
Webpacker gives you a default set of configuration files for test, development and
production environments in config/webpack/*.js. You can configure each individual
environment in their respective files or configure them all in the base
config/webpack/environment.js file.
By default, you shouldn't have to make any changes to config/webpack/*.js
files since it's all standard production-ready configuration. However,
if you do need to customize or add a new loader, this is where you would go.
You can add additional loaders beyond the base set that webpacker provides by
adding it to your environment. We'll use json-loader as an example:
yarn add json-loader
// config/webpack/environment.js
const { environment } = require('@rails/webpacker')
environment.loaders.add('json', {
test: /\.json$/,
use: 'json-loader'
})
module.exports = environment
Finally add .json to the list of extensions in config/webpacker.yml. Now if you import() any .json files inside your javascript
they will be processed using json-loader. Voila!
You can also modify the loaders that webpacker pre-configures for you. We'll update
the babel loader as an example:
// config/webpack/environment.js
const { environment } = require('@rails/webpacker')
// Update an option directly
const babelLoader = environment.loaders.get('babel')
babelLoader.options.cacheDirectory = false
module.exports = environment
The process for adding or modifying webpack plugins is the same as the process for loaders above:
// config/webpack/environment.js
const { environment } = require('@rails/webpacker')
// Get a pre-configured plugin
environment.plugins.get('ExtractText') // Is an ExtractTextPlugin instance
// Add an additional plugin of your choosing
environment.plugins.add('Fancy', new MyFancyWebpackPlugin)
module.exports = environment
By default, webpacker ships with simple conventions for where the javascript
app files and compiled webpack bundles will go in your rails app,
but all these options are configurable from config/webpacker.yml file.
The configuration for what Webpack is supposed to compile by default rests
on the convention that every file in app/javascript/packs/*(default)
or whatever path you set for source_entry_path in the webpacker.yml configuration
is turned into their own output files (or entry points, as Webpack calls it).
Suppose you want to change the source directory from app/javascript
to frontend and output to assets/packs. This is how you would do it:
# config/webpacker.yml
source_path: frontend
source_entry_path: packs
public_output_path: assets/packs # outputs to => public/assets/packs
Similarly you can also control and configure webpack-dev-server settings from config/webpacker.yml file:
# config/webpacker.yml
development:
dev_server:
host: localhost
port: 8080
If you have hmr turned to true, then the stylesheet_pack_tag generates no output, as you will want to configure your styles to be inlined in your JavaScript for hot reloading. During production and testing, the stylesheet_pack_tag will create the appropriate HTML tags.
If you are adding webpacker to an existing app that has most of the assets inside
app/assets or inside an engine and you want to share that
with webpack modules then you can use resolved_paths
option available in config/webpacker.yml, which lets you
add additional paths webpack should lookup when resolving modules:
resolved_paths: ['app/assets']
You can then import them inside your modules like so:
// Note it's relative to parent directory i.e. app/assets
import 'stylesheets/main'
import 'images/rails.png'
Note: Please be careful when adding paths here otherwise it will make the compilation slow, consider adding specific paths instead of whole parent directory if you just need to reference one or two modules
Webpacker ships with babel - a JavaScript compiler so
you can use next generation JavaScript, today. The Webpacker installer sets up a
standard .babelrc file in your app root, which will work great in most cases
because of babel-env-preset.
Following ES6/7 features are supported out of the box:
We have also included babel polyfill that includes a custom regenerator runtime and core-js.
Webpacker out-of-the-box provides CSS post-processing using
postcss-loader
and the installer sets up a standard .postcssrc.yml
file in your app root with standard plugins.
plugins:
postcss-smart-import: {}
postcss-cssnext: {}
Webpacker out-of-the-box provides CDN support using your Rails app config.action_controller.asset_host setting. If you already have CDN added in your rails app
you don't need to do anything extra for webpacker, it just works.
If you're using the webpack-dev-server in development, you can serve your packs over HTTPS
by setting the https option for webpack-dev-server to true in config/webpacker.yml,
then start the dev server as usual with ./bin/webpack-dev-server.
Please note that the webpack-dev-server will use a self-signed certificate,
so your web browser will display a warning/exception upon accessing the page. If you get
https://localhost:3035/sockjs-node/info?t=1503127986584 net::ERR_INSECURE_RESPONSE
in your console, simply open the link in your browser and accept the SSL exception.
Now if you refresh your rails view everything should work as expected.
Webpacker out-of-the-box supports HMR with webpack-dev-server and
you can toggle it by setting dev_server/hmr option inside webpacker.yml.
Checkout this guide for more information:
To support HMR with React you would need to add react-hot-loader. Checkout this guide for
more information:
Note: Don't forget to disable HMR if you are not running webpack-dev-server
otherwise you will get not found error for stylesheets.
Static assets like images, fonts and stylesheets support is enabled out-of-box and you can link them into your javascript app code and have them compiled automatically.
// app/javascript/hello_react/styles/hello-react.sass
.hello-react
padding: 20px
font-size: 12px
// React component example
// app/javascripts/packs/hello_react.jsx
import React from 'react'
import helloIcon from '../hello_react/images/icon.png'
import '../hello_react/styles/hello-react'
const Hello = props => (
<div className="hello-react">
<img src={helloIcon} alt="hello-icon" />
<p>Hello {props.name}!</p>
</div>
)
Under the hood webpack uses
extract-text-webpack-plugin plugin to extract all the referenced styles within your app and compile it into
a separate [pack_name].css bundle so that in your view you can use the
stylesheet_pack_tag helper.
<%= stylesheet_pack_tag 'hello_react' %>
You can also link js/images/styles used within your js app in views using
asset_pack_path helper. This helper is useful in cases where you just want to
create a <link rel="prefetch"> or <img /> for an asset.
<%= asset_pack_path 'hello_react.css' %>
<%# => "/packs/hello_react.css" %>
<img src="<%= asset_pack_path 'calendar.png' %>" />
<% # => <img src="/packs/calendar.png" /> %>
You can also import styles from node_modules using the following syntax.
Please note that your styles will always be extracted into [pack_name].css:
// app/javascript/app-styles.sass
// ~ to tell webpack that this is not a relative import:
@import '~@material/animation/mdc-animation'
@import '~bootstrap/dist/css/bootstrap'
// Your main app pack
// app/javascript/packs/app.js
import '../app-styles'
<%# In your views %>
<%= javascript_pack_tag 'app' %>
<%= stylesheet_pack_tag 'app' %>
Let's say you're building a calendar app. Your JS app structure could look like this:
// app/javascript/packs/calendar.js
import 'calendar'
app/javascript/calendar/index.js // gets loaded by import 'calendar'
app/javascript/calendar/components/grid.jsx
app/javascript/calendar/styles/grid.sass
app/javascript/calendar/models/month.js
<%# app/views/layouts/application.html.erb %>
<%= javascript_pack_tag 'calendar' %>
<%= stylesheet_pack_tag 'calendar' %>
But it could also look a million other ways.
You can also namespace your packs using directories similar to a Rails app.
app/javascript/packs/admin/orders.js
app/javascript/packs/shop/orders.js
and reference them in your views like this:
<%# app/views/admin/orders/index.html.erb %>
<%= javascript_pack_tag 'admin/orders' %>
and
<%# app/views/shop/orders/index.html.erb %>
<%= javascript_pack_tag 'shop/orders' %>
If you need more advanced React-integration, like server rendering, redux, or react-router, see shakacode/react_on_rails, react-rails, and webpacker-react.
If you're not concerned with view helpers to pass props or server rendering, can do it yourself:
<%# views/layouts/application.html.erb %>
<%= content_tag :div,
id: "hello-react",
data: {
message: 'Hello!',
name: 'David'
}.to_json do %>
<% end %>
// app/javascript/packs/hello_react.js
const Hello = props => (
<div className='react-app-wrapper'>
<img src={clockIcon} alt="clock" />
<h5 className='hello-react'>
{props.message} {props.name}!
</h5>
</div>
)
// Render component with data
document.addEventListener('DOMContentLoaded', () => {
const node = document.getElementById('hello-react')
const data = JSON.parse(node.getAttribute('data'))
ReactDOM.render(<Hello {...data} />, node)
})
Add the data as attributes in the element you are going to use (or any other element for that matter).
<%= content_tag :div,
id: "hello-vue",
data: {
message: "Hello!",
name: "David"
}.to_json do %>
<% end %>
This should produce the following HTML:
<div id="hello-vue" data="{"message":"Hello!","name":"David"}"></div>
Now, modify your Vue app to expect the properties.
<template>
<div id="app">
<p>{{test}}{{message}}{{name}}</p>
</div>
</template>
<script>
export default {
// A child component needs to explicitly declare
// the props it expects to receive using the props option
// See https://vuejs.org/v2/guide/components.html#Props
props: ["message","name"],
data: function () {
return {
test: 'This will display: ',
}
}
}
</script>
<style>
</style>
document.addEventListener('DOMContentLoaded', () => {
// Get the properties BEFORE the app is instantiated
const node = document.getElementById('hello-vue')
const props = JSON.parse(node.getAttribute('data'))
// Render component with props
new Vue({
render: h => h(App, { props })
}).$mount('#hello-vue');
})
You can follow same steps for Angular too.
The CommonsChunkPlugin is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points. By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in the cache for later use. This results in page speed optimizations as the browser can quickly serve the shared code from the cache, rather than being forced to load a larger bundle whenever a new page is visited.
Add the plugins in config/webpack/environment.js:
environment.plugins.add('CommonsChunkVendor', new webpack.optimize.CommonsChunkPlugin({
name: 'vendor',
minChunks: (module) => {
// this assumes your vendor imports exist in the node_modules directory
return module.context && module.context.indexOf('node_modules') !== -1;
}
}))
environment.plugins.add('CommonsChunkManifest', new webpack.optimize.CommonsChunkPlugin({
name: 'manifest',
minChunks: Infinity
}))
Now, add these files to your layouts/application.html.erb:
<%# Head %>
<%= javascript_pack_tag 'manifest' %>
<%= javascript_pack_tag 'vendor' %>
<%# If importing any styles from node_modules in your JS app %>
<%= stylesheet_pack_tag 'vendor' %>
While you are free to use require() and module.exports, we encourage you
to use import and export instead since it reads and looks much better.
import Button from 'react-bootstrap/lib/Button'
// or
import { Button } from 'react-bootstrap'
class Foo {
// code...
}
export default Foo
import Foo from './foo'
You can also use named export and import
export const foo = () => console.log('hello world')
import { foo } from './foo'
To add any new JS module you can use yarn:
yarn add bootstrap material-ui
You can use yarn to add bootstrap or any other modules available on npm:
yarn add bootstrap
Import Bootstrap and theme (optional) CSS in your app/javascript/packs/app.js file:
import 'bootstrap/dist/css/bootstrap'
import 'bootstrap/dist/css/bootstrap-theme'
Or in your app/javascript/app.sass file:
// ~ to tell that this is not a relative import
@import '~bootstrap/dist/css/bootstrap'
@import '~bootstrap/dist/css/bootstrap-theme'
yarn add ts-loader typescript @types/react @types/react-dom
# You don't need this with typescript
yarn remove prop-types
tsconfig.json to project root:{
"compilerOptions": {
"declaration": false,
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"lib": ["es6", "dom"],
"module": "es6",
"moduleResolution": "node",
"sourceMap": true,
"jsx": "react",
"target": "es5"
},
"exclude": [
"**/*.spec.ts",
"node_modules",
"public"
],
"compileOnSave": false
}
.tsx to the list of extensions in config/webpacker.yml
and rename your generated hello_react.js using react installer
to hello_react.tsx and make it valid typescript and now you can use
typescript, JSX with React.After you have installed angular using angular installer you would need to follow these steps to add HTML templates support:
yarn to add html-loaderyarn add html-loader
config/webpack/environment.jsenvironment.loaders.add('html', {
test: /\.html$/,
use: [{
loader: 'html-loader',
options: {
minimize: true,
removeAttributeQuotes: false,
caseSensitive: true,
customAttrSurround: [ [/#/, /(?:)/], [/\*/, /(?:)/], [/\[?\(?/, /(?:)/] ],
customAttrAssign: [ /\)?\]?=/ ]
}
}]
})
.html to config/webpacker.yml extensions:
- .elm
- .coffee
- .html
d.ts definition// app/javascript/hello_angular/html.d.ts
declare module "*.html" {
const content: string
export default content
}
app.component.ts<h1>Hello {{name}}</h1>
app.component.tsimport { Component } from '@angular/core'
import templateString from './template.html'
@Component({
selector: 'hello-angular',
template: templateString
})
export class AppComponent {
name = 'Angular!'
}
That's all. Voila!
If you are using vim or emacs and want to ignore certain files you can add ignore-loader:
yarn add ignore-loader
and add ignore-loader to config/webpack/environment.js
// ignores vue~ swap files
const { environment } = require('@rails/webpacker')
environment.loaders.add('ignore', {
test: /.vue~$/,
loader: 'ignore-loader'
})
And now all files with .vue~ will be ignored by the webpack compiler.
It's possible to link to assets that have been precompiled by sprockets. Add the .erb extension to your javascript file, then you can use Sprockets' asset helpers:
<%# app/javascript/my_pack/example.js.erb %>
<% helpers = ActionController::Base.helpers %>
var railsImagePath = "<%= helpers.image_path('rails.png') %>"
This is enabled by the rails-erb-loader loader rule in config/webpack/loaders/erb.js.
You can also use babel-plugin-module-resolver to reference assets directly from app/assets/**
yarn add babel-plugin-module-resolver
Specify the plugin in your .babelrc with the custom root or alias. Here's an example:
{
"plugins": [
["module-resolver", {
"root": ["./app"],
"alias": {
"assets": "./assets"
}
}]
]
}
And then within your javascript app code:
// Note: we don't have do any ../../ jazz
import FooImage from 'assets/images/foo-image.png'
import 'assets/stylesheets/bar'
Environment variables are supported out of the box in Webpacker. For example if you run the Webpack dev server like so:
FOO=hello BAR=world ./bin/webpack-dev-server
You can then reference these variables in your javascript app code with
process.env:
console.log(process.env.FOO) // Compiles to console.log("hello")
You may want to store configuration in environment variables via .env files,
similar to the dotenv Ruby gem.
In development, if you use Foreman or Invoker
to launch the Webpack server, both of these tools have basic support for a
.env file (Invoker also supports .env.local), so no further configuration
is needed.
However, if you run the Webpack server without Foreman/Invoker, or if you
want more control over what .env files to load, you can use the
dotenv npm package. Here is what you could
do to support a "Ruby-like" dotenv:
yarn add dotenv
// config/webpack/environment.js
...
const dotenv = require('dotenv');
const dotenvFiles = [
`.env.${process.env.NODE_ENV}.local`,
'.env.local',
`.env.${process.env.NODE_ENV}`,
'.env'
];
dotenvFiles.forEach((dotenvFile) => {
dotenv.config({ path: dotenvFile, silent: true });
});
module.exports = {
...
Warning: using Foreman/Invoker and npm dotenv at the same time can result in confusing behavior, in that Foreman/Invoker variables take precedence over npm dotenv variables.
If you'd like to pass custom variables to the compiler, use Webpack::Compiler.env attribute.
Webpacker::Compiler.env['FRONTEND_API_KEY'] = 'your_secret_key'
Webpacker hooks up a new webpacker:compile task to assets:precompile, which gets run whenever you run assets:precompile. If you are not using sprockets you
can manually trigger bundle exec rails webpacker:compile during your app deploy.
The javascript_pack_tag and stylesheet_pack_tag helper method will automatically insert the correct HTML tag for compiled pack. Just like the asset pipeline does it.
By default the output will look like this in different environments:
<!-- In development mode -->
<script src="/packs/calendar.js"></script>
<link rel="stylesheet" media="screen" href="/packs/calendar.css">
<!-- In development mode with webpack-dev-server -->
<script src="http://localhost:8080/calendar.js"></script>
<link rel="stylesheet" media="screen" href="http://localhost:8080/calendar.css">
<!-- In production mode -->
<script src="/packs/calendar-0bd141f6d9360cf4a7f5.js"></script>
<link rel="stylesheet" media="screen" href="/packs/calendar-dc02976b5f94b507e3b6.css">
Heroku installs yarn and node by default if you deploy a rails app with Webpacker so all you would need to do:
heroku create shiny-webpacker-app
heroku addons:create heroku-postgresql:hobby-dev
git push heroku master
Webpacker lazily compiles assets in test env so you can write your tests without any extra setup and everything will just work out of the box.
Here is a sample system test case with hello_react example component:
// Example react component
import React from 'react'
import ReactDOM from 'react-dom'
import PropTypes from 'prop-types'
const Hello = props => (
<div>Hello David</div>
)
document.addEventListener('DOMContentLoaded', () => {
ReactDOM.render(
<Hello />,
document.body.appendChild(document.createElement('div')),
)
})
<%# views/pages/home.html.erb %>
<%= javascript_pack_tag "hello_react" %>
# Tests example react component
require "application_system_test_case"
class HomesTest < ApplicationSystemTestCase
test "can see the hello message" do
visit root_url
assert_selector "h5", text: "Hello! David"
end
end
By default, the lazy compilation is cached until a file is changed under
tracked paths. You can configure the paths tracked
by adding new paths to watched_paths array, much like rails autoload_paths:
# config/initializers/webpacker.rb
# or config/application.rb
Webpacker::Compiler.watched_paths << 'bower_components'
ENOENT: no such file or directory - node-sass on Heroku
or elsewhere during assets:precompile or bundle exec rails webpacker:compile
then you would need to rebuild node-sass. It's a bit of a weird error;
basically, it can't find the node-sass binary.
An easy solution is to create a postinstall hook - npm rebuild node-sass in
package.json and that will ensure node-sass is rebuilt whenever
you install any new modules.Can't find hello_react.js in manifest.json
when loading a view in the browser it's because Webpack is still compiling packs.
Webpacker uses a manifest.json file to keep track of packs in all environments,
however since this file is generated after packs are compiled by webpack. So,
if you load a view in browser whilst webpack is compiling you will get this error.
Therefore, make sure webpack
(i.e ./bin/webpack-dev-server) is running and has
completed the compilation successfully before loading a view.config/webpacker.yml under dev_server's port. Alternatively, you can stop the process from occupying port 8080. To do so, simply find the process id (PID) using lsof -i :8080 and kill the process with its PID using kill -9 PID.package.json:"scripts": {
"postinstall": "npm rebuild elm"
}
This could happen if webpacker:install step is skipped. Please run bundle exec rails webpacker:install to fix the issue.
If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing yarn binstub. Please run following commands to update/add binstubs:
bundle config --delete bin
./bin/rails app:update:bin # or rails app:update:bin
If you are running Webpack on Windows, your command shell may not be able to interpret the preferred interpreter
for the scripts generated in bin/webpack and bin/webpack-dev-server. Instead you'll want to run the scripts
manually with Ruby:
C:\path>ruby bin\webpack
C:\path>ruby bin\webpack-dev-server
If you receive this error when running $ ./bin/webpack-dev-server ensure your configuration is correct; most likely the path to your "packs" folder is incorrect if you modified from the original "source_path" defined in config/webpacker.yml.
Webpacker is released under the MIT License.
FAQs
Unknown package
The npm package @rails/webpacker receives a total of 258,769 weekly downloads. As such, @rails/webpacker popularity was classified as popular.
We found that @rails/webpacker demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 8 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers unpack a typosquatting package with malicious code that logs keystrokes and exfiltrates sensitive data to a remote server.
Security News
The JavaScript community has launched the e18e initiative to improve ecosystem performance by cleaning up dependency trees, speeding up critical parts of the ecosystem, and documenting lighter alternatives to established tools.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.