1 What Is Webpacker?
Webpacker is a Rails wrapper around the webpack build system that provides a standard webpack configuration and reasonable defaults.
1.1 What is Webpack?
See the webpack documentation for information.
1.2 How is Webpacker Different from Sprockets?
If you are familiar with Sprockets, the following guide might give you some idea of how to translate. Please note that each tool has a slightly different structure, and the concepts don't directly map onto each other.
|Link to an image||image_url||image_pack_tag|
|Link to an asset||asset_url||asset_pack_tag|
|Require a script||//= require||import or require|
2 Installing Webpacker
To use Webpacker, you must install the Yarn package manager, version 1.x or up, and you must have Node.js installed, version 10.13.0 and up.
To include Webpacker in a new project, add
--webpack to the
rails new command. To add Webpacker to an existing project, add the
webpacker gem to the project's
bundle install, and then run
Installing Webpacker creates the following local files:
||A place for your front-end source|
||Configure the Webpacker gem|
||Configuration for the PostCSS CSS Post-Processor|
||Browserlist manages target browsers configuration|
The installation also calls the
yarn package manager, creates a
package.json file with a basic set of packages listed, and uses Yarn to install these dependencies.
So if you have a file called
application, and you can add it to your Rails application with the code
application.js file every time it changes, and you load a page that uses that pack. Typically, the file in the actual
import Rails from "@rails/ujs" import Turbolinks from "turbolinks" import * as ActiveStorage from "@rails/activestorage" import "channels" Rails.start() Turbolinks.start() ActiveStorage.start()
You'll need to include a pack that requires these packages to use them in your Rails application.
It is important to note that only webpack entry files should be placed in the
Typically, the pack file itself is largely a manifest that uses
require to load the necessary files and may also do some initialization.
If you want to change these directories, you can adjust the
packs) in the
Within source files,
import statements are resolved relative to the file doing the import, so
import Bar from "./foo" finds a
foo.js file in the same directory as the current file, while
import Bar from "../src/foo" finds a file in a sibling directory named
3.2 Using Webpacker for CSS
Out of the box, Webpacker supports CSS and SCSS using the PostCSS processor.
import styles/styles. This tells webpack to include your CSS file in the download. To actually load it in the page, include
<%= stylesheet_pack_tag "application" %> in the view, where the
application is the same pack name that you were using.
If you are using a CSS framework, you can add it to Webpacker by following the instructions to load the framework as an NPM module using
yarn add <framework>. The framework should have instructions on importing it into a CSS or SCSS file.
3.3 Using Webpacker for Static Assets
The default Webpacker configuration should work out of the box for static assets.
The configuration includes several image and font file format extensions, allowing webpack to include them in the generated
import myImageUrl from '../images/my-image.jpg' // ... let myImage = new Image(); myImage.src = myImageUrl; myImage.alt = "I'm a Webpacker-bundled image"; document.body.appendChild(myImage);
images, but you can use anything in
const images = require.context("../images", true) const imagePath = name => images(name, true)
Static assets will be output into a directory under
public/packs/media. For example, an image located and imported at
public/packs/media/images/my-image-abcd1234.jpg. To render an image tag for this image in a Rails view, use
The Webpacker ActionView helpers for static assets correspond to asset pipeline helpers according to the following table:
|ActionView helper||Webpacker helper|
Also, the generic helper
asset_pack_path takes the local location of a file and returns its Webpacker location for use in Rails views.
You can also access the image by directly referencing the file from a CSS file in
3.4 Webpacker in Rails Engines
As of Webpacker version 6, Webpacker is not "engine-aware," which means Webpacker does not have feature-parity with Sprockets when it comes to using within Rails engines.
Gem authors of Rails engines who wish to support consumers using Webpacker are encouraged to distribute frontend assets as an NPM package in addition to the gem itself and provide instructions (or an installer) to demonstrate how host apps should integrate. A good example of this approach is Alchemy CMS.
3.5 Hot Module Replacement (HMR)
Webpacker out-of-the-box supports HMR with webpack-dev-server, and you can toggle it by setting dev_server/hmr option inside
Check out webpack's documentation on DevServer for more information.
To support HMR with React, you would need to add react-hot-loader. Check out React Hot Loader's Getting Started guide.
Don't forget to disable HMR if you are not running webpack-dev-server; otherwise, you will get a "not found error" for stylesheets.
4 Webpacker in Different Environments
Webpacker has three environments by default
production. You can add additional environment configurations in the
webpacker.yml file and set different defaults for each environment. Webpacker will also load the file
config/webpack/<environment>.js for additional environment setup.
5 Running Webpacker in Development
Webpacker ships with two binstub files to run in development:
./bin/webpack-dev-server. Both are thin wrappers around the standard
webpack-dev-server.js executables and ensure that the right configuration files and environmental variables are loaded based on your environment.
By default, Webpacker compiles automatically on demand in development when a Rails page loads. This means that you don't have to run any separate processes, and compilation errors will be logged to the standard Rails log. You can change this by changing to
compile: false in the
config/webpacker.yml file. Running
bin/webpack will force the compilation of your packs.
ruby ./bin/webpack-dev-server. This process will watch for changes in the
Windows users will need to run these commands in a terminal separate from
bundle exec rails server.
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.
The Webpacker Documentation gives information on environment variables you can use to control
webpack-dev-server. See additional notes in the rails/webpacker docs on the webpack-dev-server usage.
5.1 Deploying Webpacker
Webpacker adds a
webpacker:compile task to the
bin/rails assets:precompile task, so any existing deploy pipeline that was using
assets:precompile should work. The compile task will compile the packs and place them in
6 Additional Documentation
For more information on advanced topics, such as using Webpacker with popular frameworks, consult the Webpacker Documentation.
You're encouraged to help improve the quality of this guide.
Please contribute if you see any typos or factual errors. To get started, you can read our documentation contributions section.
You may also find incomplete content or stuff that is not up to date. Please do add any missing documentation for main. Make sure to check Edge Guides first to verify if the issues are already fixed or not on the main branch. Check the Ruby on Rails Guides Guidelines for style and conventions.
If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.
And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome on the official Ruby on Rails Forum.