About Webpacker
This guide will show you how to install and use Webpacker to package JavaScript, CSS, and other assets for the client-side of your Rails application.After reading this guide, you will know: What Webpacker does and why it is different from Sprockets. How to install Webpacker and integrate it with your framework of choice. How to use Webpacker for JavaScript assets. How to use Webpacker for CSS assets. How to use Webpacker for static assets. How to deploy a site that uses Webpacker. How to use Webpacker in alternate Rails contexts, such as engines or Docker containers. Chapters What Is Webpacker? What is webpack? How is Webpacker Different from Sprockets? Installing Webpacker Usage Using Webpacker for JavaScript Using Webpacker for CSS Using Webpacker for Static Assets Webpacker in Rails Engines Hot Module Replacement (HMR) Webpacker in Different Environments Running Webpacker in Development Deploying Webpacker Additional Documentation 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?The goal of webpack, or any front-end build system, is to allow you to write your front-end code in a way that is convenient for developers and then package that code in a way that is convenient for browsers. With webpack, you can manage JavaScript, CSS, and static assets like images or fonts. Webpack will allow you to write your code, reference other code in your application, transform your code, and combine your code into easily downloadable packs.See the webpack documentation for information.1.2 How is Webpacker Different from Sprockets?Rails also ships with Sprockets, an asset-packaging tool whose features overlap with Webpacker. Both tools will compile your JavaScript into browser-friendly files and also minify and fingerprint them in production. In a development environment, Sprockets and Webpacker allow you to incrementally change files.Sprockets, which was designed to be used with Rails, is somewhat simpler to integrate. In particular, code can be added to Sprockets via a Ruby gem. However, webpack is better at integrating with more current JavaScript tools and NPM packages and allows for a wider range of integration. New Rails apps are configured to use webpack for JavaScript and Sprockets for CSS, although you can do CSS in webpack.You should choose Webpacker over Sprockets on a new project if you want to use NPM packages and/or want access to the most current JavaScript features and tools. You should choose Sprockets over Webpacker for legacy applications where migration might be costly, if you want to integrate using Gems, or if you have a very small amount of code to package.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. Task Sprockets Webpacker Attach JavaScript javascript_include_tag javascript_pack_tag Attach CSS stylesheet_link_tag stylesheet_pack_tag 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 WebpackerTo use Webpacker,
Key features of the Webpacker that are enabled through these drivers include:
- Webpacker and CSP Issue 1057 rails/webpacker - GitHub
- NetDefender/vscode-ts-webpack: Example of webpack - GitHub
- GitHub - Izhaki/nodemon-webpack-plugin: A webpack plugin that
- webpacker installation issue Issue 1041 rails/webpacker
- Docker Rails app error with webpacker's config? Webpacker
- Does it make sense to read the webpack/Webpacker part of
- webpack - Using webpacker with a Rails engine - Stack Overflow
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 src.3.2 Using Webpacker for CSSOut of the box, Webpacker supports CSS and SCSS using the PostCSS processor.To include CSS code in your packs, first include your CSS files in your top-level pack file as though it was a JavaScript file. So if your CSS top-level manifest is in app/javascript/styles/styles.scss, you can import it with import styles/styles. This tells webpack to include your CSS file in the download. To actually load it in the page, include 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, typically yarn add . The framework should have instructions on importing it into a CSS or SCSS file.3.3 Using Webpacker for Static AssetsThe 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 manifest.json file.With webpack, static assets can be imported directly in JavaScript files. The imported value represents the URL to the asset. For example: 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); If you need to reference Webpacker static assets from a Rails view, the assets need to be explicitly required from Webpacker-bundled JavaScript files. Unlike Sprockets, Webpacker does not import your static assets by default. The default app/javascript/packs/application.js file has a template for importing files from a given directory, which you can uncomment for every directory you want to have static files in. The directories are relative to app/javascript. The template uses the directory images, but you can use anything in app/javascript: 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 app/javascript/images/my-image.jpg will be output at public/packs/media/images/my-image-abcd1234.jpg. To render an image tag for this image in a Rails view, use image_pack_tag 'media/images/my-image.jpg.The Webpacker ActionView helpers for static assets correspond to asset pipeline helpers according to the following table: ActionView helper Webpacker helper favicon_link_tag favicon_pack_tag image_tag image_pack_tag 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 app/javascript.3.4 Webpacker in Rails EnginesAs 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
