This are the steps I needed to do to add esbuild to an application that used the vanilla rails asset pipeline with sprockets before.
.nvmrc
with your preferred node version (and install it)jsbundling-rails
and foreman
to your Gemfile
:
gem 'jsbundling-rails'
group :development, :test do
gem 'foreman'
# ...
end
bundle install
bin/rails javascript:install:esbuild
in a console to prepare esbuild.yarn install
to install all packages so faryarn add esbuild-plugin-import-glob
yarn add esbuild-sass-plugin
esbuild.config.js
in the root folder of your project. A minimal config could look like this (kudos to Arne Hartherz):
const railsEnv = process.env.RAILS_ENV || 'development'
const optimize = railsEnv !== 'development'
const path = require('path')
const { default: importGlob } = require('esbuild-plugin-import-glob')
const { sassPlugin } = require('esbuild-sass-plugin')
require('esbuild')
.build({
entryPoints: [
'application.js',
],
bundle: true,
outdir: path.join(process.cwd(), 'app/assets/builds'),
absWorkingDir: path.join(process.cwd(), 'app/assets'),
color: true,
minify: optimize,
sourcemap: true,
plugins: [
importGlob(),
sassPlugin({ cache: true }),
],
})
package.json
to use your config file for the build command:
"scripts": {
"build": "node esbuild.config.js"
}
esbuild.config.js
. This will be your pack names. E.g.:
require('esbuild')
.build({
entryPoints: [
'frontend.js',
'backend.js',
],
// ... (more config)
import
statements to import everything you need, e.g. frontend.js
:
import './frontend/stylesheets/base.sass'
import './frontend/stylesheets/blocks/**/*.sass'
import 'unpoly/unpoly.js'
import 'unpoly/unpoly.css'
yarn build
(or yarn build --watch
) and resolve all errors.
@import
statements to use relative paths.yarn add
(e.g. yarn add bootstrap@4.5.0
). Note that esbuild might complain if there are references to fonts or images in a libraries' css, because it can't load them. Tell esbuild to ignore them by marking them as external in esbuild.config.js
:
external: ['*.ttf'],
During the next steps you have to make sure that sprockets serves them correctly and rewrites the paths if necessary.Rails.application.config.assets.precompile
that are no longer necessary, because you now load those libraries through esbuild.app/assets/config/manifest.js
file to include only the folders that sprockets needs to take care of, e.g.:
//= link_tree ../builds/
//= link_tree ../fonts/
//= link_tree ../images/
Also add library fonts or images there.rails assets:clobber assets:precompile
and resolve all errors.rails assets:clobber
to remove the precompiled assets again.stylesheet_link_tag
and javascript_link_tag
to match the new pack names.bin/dev
and check that everything works and looks good.sass-rails
or uglifier
Try to check things one at a time. Does esbuild create your packages and move them to the destined folder (yarn build --watch
)? If yes, does Sprockets move that file to the public
folder (rake assets:precompile
and rake assets:clobber
)? Are the paths and digests correct?